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“ Introduetion 


Section 1 


Introduction 


The Tektronix Signal Processing and Display (SPD) package provides a wide 
range of capabilities including waveform acquisition, waveform generation, sig- 
nal processing, mathematical functions, waveform graphics, waveform manipula- 
tion and waveform file I/O. 


The SPD package consists of the following parts: 


@ The SPD Signal Processing and Acquisition Libraries—a comprehensive 
collection of signal processing and waveform manipulation routines. 
Major function categories include: waveform acquisition (from most 
Tektronix digitizers), standard signal generation, transferring 
waveforms to and from arrays and disk files, real and complex 
waveform arithmetic, real and complex fft’s and inverse fft’s, correlation 
and convolution, integration and differentiation, interpolation and 
decimation, waveform and pulse measurements, FIR filter generation, 
and support functions. 


@® The SPD Acquisition Libraries—a comprehensive collection of signal 
acquisition routines (from most Tektronix digitizers.) Like 
SPDMENJU, the acquisition library functions implement automated ac- 
cess to as many of the acquisition modes and capabilities of the targeted 
Tektronix digitizers as possible. In fact, each function corresponds to a 
SPDMENU built-in acquisition driver and provides all of the functions 
of that driver to your C and QuickBASIC programs. The capabilities in- 
clude automatic location of the address of the digitizer, automatic ac- 
quisition, scaling, and conversion to the SPD waveform format. 


@ The SPD Waveform Graphics Library-a library of high level functions 
that allows you to display data from SPD waveforms or your own data 
arrays. The functions take care of data scaling, axis and tic mark genera- 
tion (in consistent engineering units), axis, curve, and plot labeling, grid 
placement, and linear or logarithmic plotting of one or more curves, 
automatically. You can override the automatic scaling, if necessary. 
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@ QuickBASIC 4.0 Interface Library—The standard SPD libraries are im- 


plemented in Microsoft C and can be called from Microsoft C version 
5.0 or 5.1. SPD also provides an interface to the SPD libraries for 
Microsoft QuickBASIC 4.0, a powerful version of compiled BASIC. 
(The interface library does not re-implement the functions of the Signal 
Processing, Acquisition, and Waveform Graphics libraries, but rather, 
provides an inter-language calling capability so that QuickBASIC 
programs actually use the same libraries as C programs to perform the 
SPD functions.) 


SPDMENU-a program that provides easy menu-based access to al- 
most all of the SPD functions. Whether you are beginning to learn 
SPD, are trying to prototype your application interactively before writ- 
ing a program, or are using SPOMENU’s interactive capabilities to per- 
form one-time waveform analysis, SPDMENU’s automatic waveform 
graphing, on-line help, and automatic units processing will make your 
job simpler and quicker. SPDMENU even includes the capability to ac- 
cess your own custom code (C or QuickBASIC) from the menu, giving 
you the best of menu-based and program-based signal processing. 


Device Independent Graphics Drivers—Both the SPD Waveform 
Graphics Library and SPDMENU use the GSS*CGI drivers to provide 
high quality output to almost any display, printer, or plotter that you 
may wish to use. 


New Features 


Version 2.2 of SPD provides many new features which are detailed in the follow- 
ing sections. Check the file README.DOC on disk 1 for features and changes 
that have occurred since this manual was written. New features include: 


1-2 


@ New CGI device drivers including PEP301.SYS, a driver for high resolu- 


tion displays such as the 800 x 600 display found on the Tektronix PEP 
Series of Systems Controllers. This version also contains 
HPGLPLTR.SYS, a ‘one-way’ plotter driver that supports the 
Tektronix HC-100 as well as many other HPGL compatible plotters. In 
addition, drivers are now provided for Houston plotters, the HP 
Paintjet and the HP Deskjet, the Tektronix 4693D Color Graphics 
Printer and the Tektronix 4510A Color Graphics Rasterizer which acts 
as a CGI front end to all other Tektronix color printers. 


The acquisition library now contains functions that are functionally 
equivalent to the acquisition menus in SPDMENU. The Tektronix 
2432, 2440, 5223, 11801, and 11802 have been added to the list of 
digitizers from which waveforms can be acquired automatically, both by 
SPDMENU and your programs. 


@ Alternate batch files are included for the QuickBASIC interface that 


support version 4.00b of QuickBASIC. A set of batch files is also in- 
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cluded that link with BRUN40.LIB (instead of BCOM40.lib) for 
programs that use chaining. 


@ SPD now reads and writes ADIF (Analog Data Interchange Format), a 
new standard file format for waveform storage which can be also writ- 
ten by the Tektronix GURU II utility GURUADIF and some other 
Tektronix software packages. Note that this version of ADIF is dif- 
ferent from that found in earlier versions of SPD. A utility is included 
with SPD that reads older SPD files and converts them to the new 
ADIF standard. An updated version of GURUADIF is also included 
(See the README.DOC file on disk 1 for information on the location 
of these utilities and how to use them.) 


@ The SPD FFT and inverse FFT routines are no longer limited to 
waveform lengths that are a power of two. Although FFT speed 
decreases for waveforms that are not a power of two points in length, 
any length greater than sixteen is accepted if the waveforms and inter- 
mediate arrays fit in memory. From within SPDMENU, waveforms up 
to 4096 points in length can be successfully processed with the FFT and 
correlation functions. User programs, since they are usually much 
smaller than SPDMENU, can auto-correlate or take the FFT of 
waveforms up to 8192 points long. 


@ Include files are now provided for QuickBASIC 4.0 as well as for C. 
The new QuickBASIC .bi include files define equivalents of all the con- 
stants contained in the C .é files. Both the QuickBASIC and C include 
files now provide full functional prototypes. Functional prototypes 
specify the parameter types of the SPD functions so that erroneous func- 
tion arguments can be detected at compile time rather than at run time. 


@ The background color of the SPDMENU display can be changed to suit 
your preferences. 


@ Both 5.25" and 3.5" diskettes are provided. The four 3.5" diskettes each 
hold the contents of two 5.25" diskettes. For example, Disk A is 
equivalent to Disk 1 + Disk 2. 


@ The wf to _afile function (bwftoafile for QuickBASIC) no longer uses a 
dummy ‘annotate’ parameter. The parameters for wf_to_afile and 
wf _to_file are now the same. 


@ The get2430s form in SPDMENU works with both the Tektronix 2220 
and 2221 with the RS-232 option. In both cases, you must set Data 
Source to REF4 and Normalize to NO because of the limitations of the 
digitizers. 


notes that can be associated with a waveform display has been in- 


@ @ For advanced waveform graphics users, the maximum number of text 
creased from 24 to 48. 
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Figure 1-1 shows how the Tektronix Signal Processing and Display package is or- 
ganized. 


WAVEFORM 
SPDMENU EFO 
USER INTERFACE DATA FILES 


-KBASIC 


QUIC 
PROGRAM 


Fig. 1-1. Organization of the SPD package. 
Bug Fixes 


Version 2.2 of SPD fixes a number of problems found in earlier versions. These 
include: 


@ The Settings menu of SPDMENU has a field for setting the waveform 
storage directory. If it was set to a value other than "." (current direc- 
tory) that directory was used for writing but not for reading waveforms. 


@ The incorrect positioning of modules in overlays caused excessive over- 
lay thrashing when generating random waveforms from SPDMENU. 
The overlay structure has been corrected. 


@ Tek 7912 acquisition did not work correctly in version 2.1 of 
SPDMENU. 


@ Ifawaveform greater than 512 points long was displayed using markers 
rather than a line, random output occurred. This is no longer true. 


@ Performing FFT, convolution, or correlation on waveforms longer than 
4096 points generated erroneous results. 


@ IfaSPD waveform display with a dotted grid is sent to a Tektronix HC- 
100 plotter by means of the HPGLPLTR-.SYS driver over the GPIB, 
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much of the display, including curve and text, comes out as unreadable 
dotted lines. It is suspected that the cause is a timing problem. A suc- 
cessful work-around is to output the graph to a file (see Section 2 for 
details of how to do this) and then to PRINT or TYPE the resulting file 
with the output re-directed to the GPIB device. (You can use the name 
of a device in the GPIB.COM device map as a DOS device!) 


@ A number of QuickBASIC interface functions were incorrectly imple- 
mented in early copies of version 2.1. They work correctly in later 
copies of that version as well as in later versions. 


How You May Use the SPD Package. 


The license on the SPD disk envelopes give you the right 
to install and run the SPD executable programs (.EXE 
and .COM files) on one machine at any one time. You 
may make copies of the SPD disks for backup purposes 
only. You may also use the SPD function libraries (.LIB 
files) on one machine at a time to develop your own ex- 
ecutable files. The executable files (EXE files) that you 
create may be executed only on that machines, unless spe- 
cial arrangements have been previously made with 
Tektronix. The GSS*CGI graphics drivers (.SYS files) 
may not be run on other machines without a re-distribu- 
tion license from Graphics Software Systems, Inc. 9590 
S.W. Gemini Drive, Beaverton, OR 97005. Phone: (503) 
641-2200. For more details, see the actual license on the 
disk envelope. In case of a conflict with this summary, 
the actual license holds. 


Required Equipment 
To use the Tektronix Signal Processing And Display package, you need the fol- 
lowing equipment: 

@ IBM PC or PC/AT compatible computer (minimum 512K memory). 


NOTE 


The Tektronix PEP Series Instrument controllers with 80386 
processor, 80387 co-processor, high resolution (800 x 600) display 
card and monitor are recommended for maamum processing 
speed and maamum graphics capabilities. 
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@ Color Graphics Adapter and monitor 
@ PC-DOS, version 2.1 or higher 


Recommended Equipment ®& 


The following equipment enhances the use or operation of the Signal Processing 
and Display package. 
@ 640K memory (required for the SPDMENU program) 


Hercules Graphics Card, EGA, VGA, or other high resolution graphics 
adapter and monitor 


Hard disk (highly recommended) 

Floating Point Math Co-processor (8087, 80287, or 80387) 
Tektronix HC-100 plotter 

Tektronix 4693 or 4696 color printer 


Optional Equipment 


The following equipment can be added to your system to further enhance the © 
use or operation of the Signal Processing and Display package. 


®@ Microsoft C 5.0 or 5.1. Required for C language programming. 

@ Microsoft QuickBASIC 4.0. Required for BASIC language program- 
ming. 

@ S3FG120—-GPIB-PCIIA GPIB board (IEEE-488) from Tektronix. A 


GPIB board (GPIB-PCII or GPIB-PCIIA) is required for waveform ac- 
quisition. S3FG100-GURU II may also be used. 


S3FG121—GPIB: Compiled BASIC Language Interface 
S3FG12—GPIB: C Language Interface 


Printers 


Plotters 


Using this Manual - A Road Map r 


Before using SPDMENU or the libraries, please refer to the appropriate sec- 
tions in this manual. 
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@ Section 1, This introduction 


@ Section 2, Getting Started, shows you how to install SPD. Installing the | 
disks onto your hard disk is a simple matter, but modifying your CON- 
FIG.SYS and AUTOEXEC.BAT files is more complicated. Be sure to 
6 follow the instructions in Section 2 carefully. 


Part 1: SPDMENU 


@ Section 3, SPDMENU Tutonal, explains the capabilities and user inter- 
face of SPDMENYJ, the interactive front end for the SPD libraries. 
Most users, whether engineers, students, or programmers, will find 
using SPDMENU a helpful way to become familiar with the use of the 
SPD libraries. Whether or not you plan to use SPD functions in your 
own programs, read this chapter when you first start using SPD. 


@ Section 4, SPDMENU Reference 


AN IMPORTANT NOTE 


The SPD libranes were designed for processing very general 
waveforms. They can handle multiple values at each point in a 
multi-dimensioned space. Most of the functions work on only the 
first set of values (tuple) in a single dimension. This is the reason 
that many functions do not scale themselves or provide automatic 
units processing. SPDMENU, which works with one dimension, 
© one tuple waveforms, DOES do automatic scaling and units 
processing. THE MAJORITY OF SPD USERS DO NOT NEED 
TO BE CONCERNED WITH MULTIPLE DIMENSIONS AND 
TUPLES. If you are writing programs using SPD functions in 
either C or QuickBASIC, you can choose versions of functions 
that work in one dimension and one tuple (e.g., use createl_wf() 
instead of create _wf(), and arrl_to_wf() instead of arr_to_wf().) 
You can probably ignore the sum_ave(), dim_reorder() and 
tup_reorder() functions completely and will probably use 
zone_dim() only to subsection waveforms along a single dimen- 
sion. If you DO need to use macros and/or functions that refer to 
tuple number or dimension number, a one-dimension, one-tuple 
waveform has only a dimension number 0 and a tuple number 0. 


Part 2: Programmers Guide 


@ Section 5, SPD C Programming, shows how to use the SPD libraries in a 
Microsoft C 5.0 or 5.1 program. If you are going to write C programs, 
this chapter will serve as a tutorial on how to structure your programs. 

_ Unfortunately, teaching programming in the C language is beyond the 

scope of this manual. Many good books exist which can provide this in- 
formation. 


@ Section 6, SPD QuickBASIC Programming, explains how to use SPD 
functions in a Microsoft QuickBASIC 4.0 program. Although 
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QuickBASIC provides all the power of C, a number of differences exist 
between the language interfaces. 


Part 3: Function Libraries 


Section 7,.An Overview of the SPD Functions, introduces the SPD signal 
processing and graphics functions. Read this chapter to acquaint your- 

self with the purpose of each function. Later, you can refer to Sections 
8, 9, 10, and 11 when you need to find the appropriate function or func- 
tions for the specific task you need to perform. 


Section 8, Signal Processing and Acquisition Functions, describes each 
function in detail. Examples are given for the most commonly used 
functions, and the syntax for both the C and QuickBASIC forms of the 
function are given. In almost all cases, the name of the QuickBASIC in- 
terface function is the same as the C function with a ‘b’ prepended and 
the underscores removed. 


Section 9, Acquisition, describes each function in detail. The syntax for 
both the C and QuickBASIC forms of the function are given. 


Section 10, Waveform Graphics, describes each function in detail. The 
syntax for both the C and QuickBASIC forms of the function are given. 


Section 11, Waveform Structure Access, describes each function in detail. 
These functions are QuickBASIC equivalents of the C waveform access 
macros. 


Appendices 
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Appendix A, Glossary, provides a glossary of SPD and signal processing 
terms. 


Appendix B, Waveform Storage Formats, describes in great detail how 
SPD stores internally. This appendix is intended for advanced users 
who want to do sophisticated waveform structure manipulation. Most 
users can successfully ignore this appendix. 


Appendix C, SPD Header Files, lists the header files provided for both 
C and QuickBASIC. This appendix is almost a necessity for use in writ- 
ing programs. C programs require inclusion of the header files. They 
are strongly recommended for use in QuickBASIC. These files define 
numerous constants that can be of use in your program. The file 
WAV.H includes definitions for a large number of macros for accessing 
SPD waveform structures. Many of them are designed for multiple 
value/point waveforms in a multi-dimensional space. For almost all 
SPD users, this will prove to be over-kill. If you need to use these 
macros with one dimension, one tuple waveforms just set the tuple or 
dimension number to zero. 


@ Appendix D, Suggested References, lists a number of books that will 


prove helpful, especially if you are new to signal processing or program- 
ming. 
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@ Appendix E, ADIF File Format, is the official specification for ADIF, 
the Analog Data Interchange Format, which is the file format used by 
SPD to store waveforms. Most users will not need to use this appendix 
much, but it will prove invaluable if you are going to edit waveform files 
or write programs that create custom ADIF files for use by SPD. 


Signal Processing & Display 1-9 


-% Getting 


: f \ * 
. ; ; : aha tint) 
; i { - : 
: ‘ 
j : : : ; 
; * ‘ ¥ : 
. ; f 
: - - 
= Ap aA re 
£ - ¥ 
# 
~ a y ¥ ns - 
: : ; : 
. f j 
; : ‘ 
= i 
2 ‘ > ‘ ; f 
F = " ea f 


Section 2 


@ Getting Started 


This chapter describes: 


® how to install SPD, 
® the file contents of the SPD distribution diskettes, and 


@ how acquired signal data can be used with the SPD package. 


Installing the SPD Disk Files 


Step 1 - Backup the SPD Diskettes 


Make a backup copy of each SPD master diskette. For instructions on how to 
make backup copies, refer to the DISKCOPY command in your DOS manual. 
Put the originals in a safe place and use the backup copies to perform the instal- 
lation. SPD comes with two sets of disks in order to work on a wide range of 
computers. The eight 5.25-inch disks are labelled Disk 1 through Disk 8. Each 
of the four 3.5 inch disks, Disk A through Disk D, corresponds to two of the 
5.25 inch disks. 


Step 2 - Install the SPD Distribution Disks on a hard disk 


Disk 1 of the SPD package (Disk A of the 3.5-inch disks) contains the SPD in- 

stallation batch files, INSTALL.BAT and INSTALL1.BAT. INSTALL.BAT al- 

lows you to install the portions of SPD that are of interest to you on the hard 
© disk of your choice. The format for using INSTALL.BAT is 


a:install drive [CGI] [LIBS] [MENU] 


Where: 
drive is the drive on which to install SPD. (e.g., C:) 
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CGI is the keyword to install the CGI device drivers. 


LIBS is the keyword to install SPD libraries and programming support files 


for C and QuickBASIC. © 


MENU is the keyword to install the SPDMENU and its help files. 
For example, 


a: install c: CGI LIBS MENU 
installs ALL of SPD to drive C: while 
a:install d: CGI 
installs the CGI drivers on drive d:. 


Make sure you put a space between the drive and the first keyword. Also, the 
keywords that you type must be all upper case or all lower case. Mixed case 
keywords are not recognized by INSTALL.BAT 


The installation batch file prompts you to install the appropriate disks for the ® 
keywords you select and copies the appropriate files to your hard disk. The fol- 

lowing directories are created on your hard disk (depending, of course, on which 
keywords you enter): 


C:\TEK directory for Tek utilities shared by other Tek software. 
C:\TEK\SPD SPD Directory 

C:\TEK\SPD\BASIC BASIC sample programs etc. 
C:\TEK\SPD\C C sample programs etc. 
C:\TEK\SPD\INCLUDE C header file 

C:\TEK\SPD\LIB C SPD libraries 

C:\TEK\SPD\MENU SPDMENU Program 
C:\TEK\SPD\MENU\HELP SPDMENU Program HELP files 


NOTE 


If you have a version of SPD earlier than 2.1 on your hard disk, it 
should be removed before installing version 2.2. Versions starting 
with 2.1 use a different directory structure than previous versions. 
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Using the CGI Drivers with SPD 


Because there is a wide variety of graphics display devices available for the IBM 
PC, the SPD software is designed to use a common interface called the Com- 
puter Graphics Interface (CGI). When SPD needs to display a graphics figure 
on your display device, it sends a command that is interpreted by a CGI device 
driver. The driver interprets the command and causes an appropriate action to 
take place on the display device, plotter, or printer. 


Before you run any programs that use SPD graphics, whether it’s the 
SPDMENU program or one you’ve written, you have to arrange for the ap- 
propriate CGI driver(s) to be loaded and initialized. This is a simple process 
that connects the CGI driver(s) to your DOS operating system, and locates im- 
portant files in the right place on your system. It also lets you select options 
(such as which work-stations (display devices) you want to use), making it easy 
for you to tailor the CGI drivers to your system. Since there are many possible 
situations and many possible display options, the procedure is not suited to an 
automated installation; you should hand tailor this part of the installation. If 
you already have an application that uses the CGI drivers, you may have done 
this already. If you don’t intend to use the SPD graphics displays, you can skip 
this part. The immediately following sections describe the procedure for a 
simple installation - i.e. a single display device. If you can use the included ex- 
ample batch files or a simple modification of them, this is all you’ll need. Later 
in this chapter, more detail is presented that will help you better understand 
what’s going on and what you have to do to handle more complex situations 
such as multiple display devices, etc. As part of installing the CGI, you will need 
to edit two DOS files: CONFIG.SYS and AUTOEXEC.BAT. DOS uses these 
files during the system initialization process. 


Step 3 - Edit Your CONFIG.SYS File 


Edit either your own existing CONFIG.SYS file or the example CONFIG.SYS 
file located on SPD Disk 1, using EDLIN.COM located on your DOS diskette 
or a Similar text editor program. The point is to declare the existence of CGI 
device drivers to DOS. 


This template shows how: 


DEVICE=C: \PATH\DEVICE .SYS[/R] 
DEVICE=C: \PATH\GSSCGI .SYS 


For SPD, PATH is: \TEK\SPD\CGI 
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Replace the term DEVICE.SYS with the name of the device driver that’s ap- 
propriate for your system. Two examples are: 


Driver Name Device 
IBMBW.SYS IBM Graphics Adapter - monochrome 
IBMEGA.SYS IBM Enhanced Graphics Adapter 


A complete list of the drivers supplied with SPD can be found in the next sec- 
tion of this chapter. You should specify the full path directory name to tell DOS 
where to find the file. The /R term is described in more detail later—for now, 
let’s assume you'll use it. 


NOTE 


The GSSCGLSYS file is the universal CGI driver that issues com- 
mands to the appropnate device driver. It must be listed after all 
other CGI device driver file names. 


As an example, a listing of the CONFIG-SYS file located on SPD Disk 1 (or 
Disk A) follows: 


FILES=20 

BUFFERS=20 

DEVICE=C ; \TEK\SPD\CGI\IBEGA.SYS /R 
DEVICE=C : \TEK\SPD\CGI\GSSCGI .SYS 


In the example, only one display device is used (the IBM Enhanced Graphics 
Adapter device driver file IBMEGA.SYS); the drivers are located in the 
C:\TEK\SPD\CGI directory, and will be loaded as memory resident (the "/R" 
option). The "FILES" and "BUFFERS" declarations are included only as ex- 
amples; they have nothing to do with CGI operation. (You can list more than 
one driver if you want and you can group drivers, so that memory is shared by 
more than one. The details for these options are provided in later parts of this 
section.) 


Under some circumstances, the DEVICE =xxx.SYS commands are not properly 
executed by DOS. Sometimes the drivers load but cannot be accessed correctly 
without first executing your program from the root directory. The solution to 
such problems is to ALWAYS use full paths (including drive letter) for 
DEVICE commands; i.e., ALWAYS use the form: 


DEVICE=C : \full\path\dddd.SYS 


After you have successfully modified your CONFIG.SYS file, you can delete all 
of the device drivers that you are not going to use. 
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Step 4- Edit Your AUTOEXEC.BAT File 


If you are going to write C or QuickBASIC programs using the SPD functions, 
you should tell the compiler and linker where the include files and libraries are 
located by adding the lines 


SET INCLUDE=C: \TEK\SPD\ INCLUDE; 
and 
SET LIBS=C: \TEK\SPD\LIB; 


to your AUTOEXEC.BAT file. Of course, you also need to add to these SET 
statements any other library or include file directories (such as the C and 
QuickBASIC directories) that you are using. 


In addition, you should modify the PATH statement to point to the following 
directories: 


C:\TEK\SPD\MENU (for SPDMENU) 
C:\TEK\SPD\c (for C programming) 
C:\TEK\SPD\BASIC (for QuickBASIC programming) 


Edit your existing AUTOEXEC.BAT file using EDLIN.COM or another editor 
program to contain the line: 


C:\TEK\SPD\CGI\DRIVERS 


NOTE 


‘It is not necessary to run DRIVERS.EXE unless you wish to pre- 
load a device driver. Pre-loading dnvers is useful for users with a 
diskette-only system who wish to start the system from one diskette 
(containing CGI and the drivers) but run with another. 


In order to use printer and plotter drivers with either your serial or parallel port, 
you need to add a MODE command statement to your AUTOEXEC.BAT file. 
For the serial port, the baud rate/data bits/stop bits settings must be specified 
to agree with your printer or plotter. With BOTH serial and parallel ports, the 
MODE command must end with ",P" which directs the port not to time out 
when retries occur. Example: 


_ MODE COM1:,1200,8,1,P 


See your DOS manual for more details. 
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SPD Disk 1 has an example AUTOEXEC.BAT file. If you have placed your 
device drivers on a disk with subdirectories, you must include, in the 

AUTOEXEC.BAT, the fully qualified DOS path the CGI must use to locate 
them. A listing of the AUTOEXEC.BAT file located on SPD Disk 1 follows: 


VERIFY=ON @ 


SET COMSPEC=C : \COMMAND . COM 

PATH=C : \DOS;C: \BIN;C:\MSC;C:\QB;C: \TEK\SPD\MENU 
C:\TEK\SPD\CGI\DRIVERS 

SET PROMPT=SpS$g 


Step 5 - Initialize the System 


After you have verified that all the files are in the proper locations, reboot your 
system so that DOS interprets the commands contained in the CONFIG.SYS 
and AUTOEXEC.BAT files. 


Resident CGI device drivers and the CGI Controller are brought into memory 
when you initialize the system, and they remain resident. DRIVERS.EXE 
preloads into the swap area the last driver for each group named in each driver 
category (DISPLAY, PRINTER, or PLOTTER) in the CONFIG.SYS file. 


No special action is required to activate CGI after initialization; it is always in & 
memory waiting to respond to graphics requests from an application program. 

The CGI Controller loads the correct device driver into memory when re- 

quested. In the SPD package, that request comes from the C function named 

gr _dev(). For example, to activate a DISPLAY device such as the IBM En- 

hanced Graphics Adaptor, the following line would be found in the C program: 


gxr_dev("DISPLAY") ; 


The SPD Disk Files 


The following sections list and briefly describe the files located on the SPD dis- 
tribution diskettes. 


Disk 1-3 (Disk A and B) Files -C er Graphics Interface (CGI 


The SPD graphics functions use the Computer Graphics Interface (CGI) to @ 
provide a universal interface to a variety of graphics display devices. Disk 1 

(Disk A) contains CGI device drivers, example boot time CGI initialization com- 

mands, and associated support files. 
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AUTOEXEC.BAT An example AUTOEXEC.BAT file that invokes 
DRIVERS.EXE for the CGI system. 


CONFIG.SYS A sample procedure file containing a list of DOS CGI 
device driver names. You can edit this file to include or 
remove any device drivers according to your need. 


DRIVERS.EXE This program loads the CGI drivers. It can be called 


from your AUTOEXEC.BAT file. 

GSSCGI.SYS A file that contains the resident portion (CGI Control- 
ler) of CGI (common to all drivers). 

HERCBW.SYS Hercules Monochrome board driver. 

IBMBW.SYS IBM Color Graphics Adapter high resolution 
monochrome driver. 

INSTALL.BAT The installation batch files for SPD. 

and INSTALL1.BAT 

IBMEGA.SYS IBM Enhanced Graphics Adapter driver. To use the 


EGA with a monochrome monitor, add the line SET 
EGA = MONO to your AUTOEXEC.BAT file. 


‘® IBMGPR.SYS IBM Graphics Printer driver 


IBMPRCOL.SYS IBM Color Printer graphics driver. This device driver 
supports paper (NARROW and WIDE) options, and 
ribbon (BLACK, RGB, and PROCESS) options. 


PACKING.LST An up-to-date listing of the files on the SPD distribu- 
tion disks. 


PEP301.SYS A high resolution graphics display driver supporting the 
Tektronix PEP Series Instrument Controller and other 
high resolution displays. 


README.DOC The latest information on SPD. Contains material not 
, found in this manual. 


\ ditional CGI device dri ebile on dite D (disk A1, "Thess incurs: 


@ DIAB150.SYS Diablo C-150 Printer driver 


EPSONLQ.SYS EPSON Letter Quality printers including the LQ800, 
LQ1000, and LQ2500. 


EPSONX.SYS EPSON 80/100 Series printer driver (includes 
MX,RX,FX, and EX-800 models). 
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HIPLOTTR.SYS Houston plotters DMP-40, DMP-41, DMP-42, DMP-S1, 
DMP-52, DMP-56, DMP-61 and DMP-62 are supported 
by this driver. See the discussion later in this section for 
SET statements needed with this driver. 


HPPLOT.SYS Driver supports the following Hewlett Packard plotters: ® 
ColorPro, DraftPro, 7470A, 7475A, 7550A, 7680A, 
7585A, 7586A. Also supports the following IBM plot- 
ters: 6180, 6182, 6184, 7371, 7372, 7374, 7375. 


LASERJET.SYS Hewlett Packard Laserjet Printer. Resolution of 75 dpi 
or 150 dpi can be specified by adding SET RESOLU- 
TION =75 or SET RESOLUTION = 150 to your 
AUTOEXEC.BAT file 


QUIETJET.SYS Hewlett Packard Quietjet Printer driver. 
THINKJET.SYS Hewlett Packard Thinkjet Printer driver. 


4 dditional CGI device dri abi tisk 3 (disk B). These in- 
clude: 


DICONILH.SYS Diablo Low Resolution (560 x 960) Inkjet Printer 
driver. The printer must be in Epson mode. & 


DICONIXH.SYS Diablo High Resolution (1128 x 960) Inkjet Printer 
driver. The printer must be in Epson mode. 


HPGLPLTR.SYS The ‘One-way’ plotter driver. It supports the Tektronix 
HC100 and other plotters. See the discussion, later in 
this section, of the SET statements needed with this 


driver. 
IBMPRO.SYS IBM Proprinter II and Proprinter XL driver. 
IBMQW3.SYS IBM Quietwriter III driver. 


IBMVGA11.SYS IBM PS/2 640 x 480 2 color display driver. 
IBMVGA12.SYS IBM PS/2 640 x 480 16 color display driver. 
IBMVGA13.SYS IBM PS/2 320 x 200 256 color display driver. 
TOSHIBA.SYS Toshiba P351 Printer driver. 
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CS5.BAT 


CSCOMP.BAT 
C5LINK.BAT 
EXAMPLE1.BAS 
EXAMPLE1.C 
EXAMPLE2.BAS 
EXAMPLE2.C 
PROCESS.BAS 


PROCESS.C 


QB4.BAT 


QB4B.BAT 


QB4R.BAT 


QB4COMP.BAT 


QB4RCOMP.BAT 


QB4LINK.BAT 
QB4BLINK.BAT 
QB4RLINK.BAT 


SIMPLE.BAS 
SIMPLE.C 


Getting Started 


Disk 4 (Disk B) Files - C/OuickBASIC I : , 


SPD disk 4 contains the following files: 


Compile and link user program in Microsoft C v5.0 or 
v5.1 


Compile portion of c5.bat 

Link portion of c5.bat 
QuickBASIC 4.0 example program 
Microsoft C example program 
QuickBASIC 4.0 example program 
Microsoft C example program 


Skeleton QuickBASIC program for the SPDMENU 
Process option 


Skeleton C program for use with the SPDMENU 
Process option 


Compile and link user program in Microsoft 
QuickBASIC v4.0 


Compile and link user program in Microsoft 
QuickBASIC v4.00b 


Compile and link user program in Microsoft 
QuickBASIC v4.0 with BRUN40.LIB (to allow program 
chaining) 


Compile portion of qb4.bat 
Compile portion of qb4r.bat 


Link portion of qb4.bat 
Link portion of qb4b.bat 
Link portion of qb4br.bat 


Sample QuickBASIC v4.0 program 
Sample Microsoft C program 
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EQ _ FUSER.C Eq fir functions that can be modified by the user. See 
EQ FIR in Section 8 for more information. 


** C include files ** 


TEKSPD.H Master SPD include file (includes all others except © 
eq fir) 

ACQ.H definitions for use with the SPD acquisition library func- 
tions. 

EQ FIR.H definitions for use with FIR filter programs 

MACHDEP.H machine dependent definitions 

SP.H signal processing definitions 

SPD.H general definitions used throughout SPD 

TEKGR.H graphics definitions 

WAV.H waveform definitions and access macros 


** QuickBASIC include files ** 


TEKSPD.BI Master SPD include file (includes all others except 
eq fir) ® 

ACQ.BI definitions for use with the SPD acquisition library func- 
tions. 

EQ FIR.BI definitions for use with FIR filter programs 

SP.BI signal processing definitions 

SPD.BI general definitions used throughout SPD 

TEKGR.BI graphics definitions 

WAV.BI waveform definitions (access macros are functions in 
QBASIC) 

ACQMS.LIB SPD Waveform Acquisition Library (C & QuickBASIC) 

GRMS5.LIB SPD Waveform Graphics Library (C & QuickBASIC) 
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Disk 5 (Disk C) Files - C/QuickBASIC I S } 
SPD disk 5 (disk C) contains the following files: © 


FPEMS.OBJ Floating point exception handlers 
SPDB.LIB QuickBASIC 4.0 interface to the SPD libraries 
SPDMS.LIB The SPD signal processing library 

Disk 6 (Disk C) Files - SPD MENU 


SPD disk 6 (disk C) contains the following files: 


SM.EXE The actual SPDMENU executable code 
SPDMENU.BAT The batch file that runs SM.EXE, the SPDMENU ex- 
ecutable. 
Disk 7 (Disk D) Files - SPD MENU 


SPD disk 7 (disk D) contains the following files: 


*. HLP FILES The SPDMENU HELP files 
PUT2430.DOC Documentation for using PUT2430.EXE 
PUT2430.EXE An external driver that allows you to send a waveform 


to the Tektronix 2430, 2430A, 2432, or 2440. This 
program can be invoked from the DRIVER menu. 


SPDMENU.M The SPDMENU menu definition file 


TEKLOGO.COM _ The executable file that paints the Tektronix logo on 
the screen. Used by SPDMENU.BAT. 


Disk 8 (Disk D) Files - New CGI Dri 


SPD disk 8 (disk D) contains the following files: 


HPDJET.SYS Hewlett Packard DeskJet printer driver. 

HPPJ90.SYS Hewlett Packard PaintJet printer driver (90 DPI only). 
TEK4693D.SYS Tektronix 4693d Color Graphics Printer driver 
TEK4696.SYS Tektronix 4696 Color Graphics Copier driver 
TEK4510A.SYS Tektronix 4510a Color Graphics Rasterizer driver. The 


4510a will drive any of the Tektronix color printers. 
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NOTE 


The CGI pnnter drivers now have the hardware fonts that they sup- 

port in separate .FNT files. While SPD does not use these files, 

they must be present in the same directory as the printer dnvers for 

the drivers to work. The installation batch files put them there. @ 


HW_12x8.FNT Hardware font files needed by CGI printer drivers 
HW_12x16.FNT 

HW_12x24.FNT 

HW_12x48.FNT 

HW_18x24.FNT 

HW_24x24.FNT 

HW_6x8.FNT 

HW_6x16.FNT 


Additional drivers or utilities may be available. Check the README.DOC file 
on disk 1 (disk A) for details. 


Installing CGI - More Detail 6 


The following sections provide more detail on setting up the CGI programs on 
your system. Information on how to deal with more than one display type, more 
than one device of a given display type, grouping display devices, setting printer 
and ribbon options, etc., is included. 


The CONFIG.SYS File 


When editing the CONFIG.SYS file, you select options specific to your system. 
You can select the device drivers to be available to graphics application 


programs. 
Device Driver Availability 


Each device to be supported by the CGI on your system requires a specific 
device driver. Each driver that is to be available to the CGI must be included in 
the CONFIG.SYS file. You will need to modify the CONFIG.SYS file, using 
EDLIN.COM located on your DOS diskette or a similar editor program, to in- 
clude the GSSCGISYS file and all the device drivers that are to be accessible to 
your graphics programs. 
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NOTE 


The GSSCGLSYS file must always be listed after all other CGI 
device drivers. 


® Using the DOS DEVICE Command 


The DOS DEVICE command allows you to specify the name of a file contain- 
ing a device driver. If you want device drivers to be available, you must include 
a DEVICE command for each device driver. The file names must be included 
in the CONFIG.SYS file in this manner: 

DEVICE=C: \TEK\SPD\CGI\filename.sys [/R] 

DEVICE=C : \TEK\SPD\CGI\filename.sys [/G [:group name] ] 


DEVICE=C : \TEK\SPD\CGI\GSSCGI .SYS 


where "filename.sys" is the name of your device driver. 


Options for CGI Work-stations 


memory when either DRIVERS.EXE is run, or when 
the device driver is first called in by a call to gr _dev(). 
The device driver does not swap in and out of memory 
as it does when the /R option is not specified. 


® /R[ESIDENT] The /R option causes the device driver to load into 


/G[ROUP][:group The /G:group name option causes device drivers to 
name] share (swap) memory with other drivers in the same 
group or default value. 
You can create multiple groups by using a different 
name for each group. The group name can be from 1 to 
7 characters in length and must begin with an alphabeti- 
cal character. The groups are limited in number by the 
amount of memory in your system. 
In each group, only one work-station can be open at 
one time. 


NOTE 


If neither /R nor /G are specified, the default value is /G with no 


"group name". If you specify any / option, you must include two 
blank spaces between filename.sys and the slash "/". 
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Creating DEVICE Commands 


Examples of the DEVICE commands you can create are: 


DEVICE=C : \TEK\SPD\CGI\IBMEGA.SYS /R © 


The Enhanced Graphics Adapter driver, once loaded into memory, remains resi- 
dent until the system is rebooted. 


DEVICE=C : \TEK\SPD\CGI\IBMEGA.SYS /G:gl 
DEVICE=C : \TEK\SPD\CGI\IBMGPR.SYS /G:gl 


Both the Enhanced Graphics Adapter driver and the IBM graphics printer 
driver share the same memory space for group g/. They are swapped in memory 
from disk when their work-station is called by a CGI function. Therefore, only 
one device driver is resident at a time and only one work-station in a swap area 
can be open at a time. Enough space for the larger of the two drivers is 
automatically allocated. 


DEVICE=C : \TEK\SPD\CGI\ IBMEGA.SYS 


DEVICE#=C : \TEK\SPD\CGI\ IBMPRCOL .SYS 


Both the IBM Enhanced Graphics Adapter driver and the Color Printer driver 
share the same memory space allocated for the unnamed default group. ® 


If there is more than one driver with the same logical device type (such as multi- 
ple display, or printer drivers) the last one encountered in the CONFIG.SYS file 
is assigned the default logical name. For more information on default logical 
names, refer to "Default Logical Names" in this section. 


Using Logical Names 
If CONFIG.SYS contains: 
DEVICE=C : \TEK\SPD\CGI\HERCBW.SYS 
DEVICE#C : \TEK\SPD\CGI\ IBMEGA.SYS 
DEVICE=C : \TEK\SPD\CGI\GSSCGI .SYS 
then an application can open the EGA device driver with the command 


gr_dev("DISPLAY") ® 


The logical name DISPLAY uses the IBMEGA.SYS device driver, because it is 
the last driver of the DISPLAY class to be listed. 
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If HERCBW.SYS is to be used also, you must use a SET command to define a 
new logical name for use in gr _dev() calls. The command 


SET DISPLAY2 = HERCBW.SYS 
enables opening the Hercules device driver with the command 
gr_dev("DISPLAY2") ; 


NOTE 


CGI does not automatically assign additional logical names for 
the same work-station type. 


The resident portion of CGI inspects the DOS environment for logical device 
names that are SET to device driver filenames. The CGI then finds the logical 
name that is SET to a device driver name when an application sends any output 
to a device. 


Default Logical Names 


The logical names specify categories of work-stations. The default logical names 
CGI assigns, along with a description of each, are as follows: 


DISPLAY The logical default name for a Display device driver. 
The last device driver of a Display type in the CON- 
FIG.SYS file is assigned the logical name DISPLAY. 


PLOTTER The logical default name for a Plotter device driver. 
The last device driver of a Plotter type in the CON- 
FIG.SYS file is assigned the logical name PLOTTER. 


PRINTER The logical default name for a Printer device driver. 
The last device driver of a Printer type in the CON- 
FIG.SYS file is assigned the logical name PRINTER. 


Assigning Device Driver Options 


Many CGI device drivers examine the DOS environment for orientation, ribbon 
or paper selections. The ORIENTATION option is supported by all of the 
printer and plotter drivers. The PAPER option is supported by the EPSONX, 
EPSONLQ, QUIETJET, HPDJET, HPPJ90, THINKJET (ISOA4 only), 
TOSHIBA, IBMPRO, and IBMQWS3 drivers. The RIBBON option is sup- 
ported only by the IBMCOL driver. 
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The selections can be set in AUTOEXEC.BAT or from the DOS prompt using 
the SET command, as follows: 


SET OPTION=VALUE 
When entering SET options, be sure there are no spaces around the ’=’. © 
The parameters for the options are: 

ORIENTATION The orientation options are: 


PORTRAIT (default) 
LANDSCAPE 


PAPER The paper options are: 


NARROW - 8 inch wide output (default) 
WIDE - 14 inch wide output 


ISOA4 - European paper (210mm x 297mm) 
RIBBON The ribbon options are: 


BLACK - black ribbon, 2 colors @ 
RGB _ -red, green, blue, and 

black ribbon, 5 colors 
PROCESS - process ribbon, 8 colors (default) 


On most printers, the highest available resolution is used. The THINKJET.SYS 
driver uses 96 dpi, unless the option line: 


SET RESOLUTION=192 


is used. 


The TEK4693D.SYS driver offers RESOLUTION states of LOW (75 dpi), 
MEDIUM (150 dpi, the default), HIGH (240 dpi), and SUPER (300 dpi.) 
Legal PAPER values are A (the default) and LEGAL. 


NOTE 


To use the SUPER resolution option (300dpi) on the 4693D, you © 
must Set the printer’s front panel window, SELECT PICTURE 
POSITION IN MEDIA, to landscape-oriented. 
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An additional environment variable is available called INVERT, for both the 
4693D driver and the 4510A driver. By default, both drivers map black pixels to 
white and white to black. You can overide this by adding the command: 


SET INVERT=OFF 


NOTE 


To use the WIDE paper option, the appropriate printer DIP switch 
must be set properly. For more information on setting printer DIP 
switches, refer to your printer manual. 


The PEP301.SYS High Resolution Display Driver 


If you have a high resolution color monitor and graphics card, you will want to 
use the PEP301.SYS graphics driver. This driver supports the Tektronix PEP 
Series Instrument Controller display (800x600 default resolution) as well as 
other color graphics cards, including: 


Graphics Board Default Resolution 
Paradise AutoSwitch EGA 480 640x480 
Quadram ProSync 640x480 
Video7 Vega Deluxe 640x480 
Video7 Vega VGA 800x600 
ATI VIP 800x560 
ATI EGA Wonder 800x600 
Tecmar EGA Master 800 800x600 
Genoa Super EGA 800x600 
Other (Enhanced Display) 640x350 
Other (Color Display) 640x200 
Monochrome Display NOT SUPPORTED 


EGA cards with less than 256k of display memory are not supported. The 
default resolutions mentioned above are automatically used by the driver unless 
you override them by using a SET command. SPDMENU, for example, works 
best with a resolution of 640x480 or 640x350, because higher resolutions com- 
press the text of the menu portion too much. You will probably want to use the 
highest resolution available for your board when graphing from your own 
programs or when using SPD for complex graphs. From the DOS prompt or 
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your AUTOEXEC.BAT file, use these SET commands to override default 
resolutions: 


Command | Resolution 
SET EGA =MR3 320x200 ® 
SET EGA=HR3 640x200 
SET EGA=HR4 640x350 (same as IBMEGA.SYS) 
SET EGA = 640x480 640x480 
SET EGA = 800x560 800x560 
SET EGA = 800x600 800x600 


If your graphics card does not work with a given setting, the attempt to open the 
display returns an error. 


NOTE 


You cannot use a resolution higher than the default resolution for 
your card. 
Note also that it is NOT necessary to reboot to change your resolu- 


tion. Simply eat the program, type the SET command and re-ex- 
ecute the program. _ 


The HIPLOTTR.SYS Houston Instruments Plotter Driver 


The Houston Instrument Plotter driver depends on you to define the plotter 
characteristics via a SET command rather than by holding a 2 way dialog with 
the plotter. This makes plotting via a GPIB connection possible (see below for 
details.) The basic SET command for the HIPLOTTR.SYS driver is: 


SET HI_TYPE=<plotter id>,<page size>,<number of pens> 


where: 


<plotter id> can be 29, 20, 41, 42, 51, 52, 56, 61, or 62. Each value corresponds 
to one of the DMP-x models where xx is the plotter id. 


A3, or A4 (European standard page sizes). Each plotter id has a corresponding 
default paper size appropriate for that model, but this field lets you override the 
default. 


<page size> can be A, B, C, D, or E (ANSI standard page sizes) or AO, Al, A2, ® 
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<number of pens> is a small positive integer; e.g., 4 or 8. Each plotter id has a 
corresponding default number of pens appropriate for that model, but this field 
lets you override the default. 


The output of the HIPLOTTR.SYS driver is, by default, routed to COM1:. You 
can redirect it (you can do this to other drivers too) by using the following SET 
commands: 


1. SET PLOTTER=HIPLOTTR (use PRINTER for printers, of course) 
2. SET HIPLOTTR=COMn where n =2, 3, or 4 (for other serial ports) 
or 
SET HIPLOTTR = \full\path\of\target\ file 


If you want to route output to a file, the file must ALREADY EXIST (create a 
dummy file, if necessary). 


The HPGLPLTR.SYS ‘One-Way’ Plotter Driver 


This new plotter driver supports HPGL plotters as does HPPLOT.SYS, but dif- 
fers in that it depends on you to define the plotter characteristics via a SET com- 
mand rather than by holding a 2 way dialog with the plotter. This makes plotting 
via a GPIB connection possible (see below for details.) It also makes possible 
the use of plotters, such as the Tektronix HC100, which are always in a Listen 
Only mode and thus do not respond to conversation attempts by the controller. 


The SET command for the HPGLPLTR.SYS driver is: 
SET HP_TYPE=<plotter id>,<page size>,<number of pens> 


where: 


<plotter id> can be 980, 990, 2000, and 3300 for Roland DG plotters; 7440, 
7470, 7475, 7550, and 7580 for HP plotters. 


<page size> can be A, B, C, D, or E (ANSI standard page sizes). 
<number of pens> is a small positive integer e.g. 4 or 8. 


For example, the Tektronix HC100 plotter is compatible with the HP7470, takes 
A size paper and has four pens. The appropriate SET command for the HC100 is: 


SET HP_TYPE=7470,A,4 
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The output of the HPGLPLTR-SYS driver is, by default, routed to COM1:. 
You can redirect it (you can do this to other drivers too) by using the following 
SET commands: 


1. SET PLOTTER=HPGLPLTR (use PRINTER for printers, of course) 
2. SET HPGLPLTR=LPT1 (for parallel port) © 
or 
SET HPGLPLTR=PLOT1 (use GPIB device name here) 
Or 
SET HPGLPLTR = \full\path\of\target\ file 


If you use the GPIB option, the device must be defined in your GPIB.COM 
map, which can be modified with the IBCONF.EXE command. The device 
name should NOT be a TEKDEVn or DEVn format name (where x is a small 
integer), since SPD uses these names for acquisition. In addition, the address of 
the plotter must be higher than that of any digitizer from which you will use 
SPDMENU or a SPD acquisition function to acquire waveforms. 


If you want to route HPGL output to a file, the file must ALREADY EXIST © 
(create a dummy file, if necessary). 


Data Acquisition and the SPD Package 


For the SPD package, data acquisition can be defined as the process of retriev- 
ing waveform data from an instrument or file and then creating a memory-resi- 
dent waveform data structure representing the acquired data (the SPD 
Waveform Processing functions require waveform data to reside in memory as a 
Waveform Data Structure). 


The SPD package provides four methods for accomplishing this task: 


@ For most Tektronix digitizers, SPDMENU provides menu interfaces 
that perform the complete process of acquiring the data from the instru- 
ment, allocating the space for the SPD waveform structure, and convert- 
ing the acquired data to the SPD format. A pointer to the new 
waveform is returned. The digitizers covered in SPDMENU now in- © 
clude the Tektronix 2220, 2221, 2230, 2430, 2430A, 2432, 2440, 5223, 
7D20, 7912AD, 7912HB, 11401, 11402, RTD710, and RDT710A 
digitizers. 
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@ With the exception of the Tektronix 2230 RS-232 form, all of 
SPDMENU’s acquisition functionality is now provided in the acquisi- 
tion library, ACQMS.LIB. The functions are named exactly the same 
as the corresponding menu, and have parameters corresponding to the 
fields in the menu. The include files, ACQ.H for C and ACQ.BI for 
QuickBASIC, provide predefined constants for all of the multi-valued 
fields that correspond to the values displayed by SPD MENU. For more 
detail, see Section 9. USE THESE FUNCTIONS IF AT ALL POS- 
SIBLE. They provide the widest possible coverage of data channels, ac- 
quisition modes, and GPIB parameters, and they are as easy to use as 

_ the SPDMENU equivalents. 


@ For digitizers not covered above, you can use the arr_to wf() or 
arrl_to_wf() functions to convert the most widely used in-memory rep- 
resentation of a waveform (an array) to a memory-resident waveform 
data structure. The wf_to_arr() function performs the reverse opera- 
tion. 


@ You can also use the file_to_wf() or afile_to_wf() to convert data binary 
or ASCII files that conform to the ADIF file format, into memory-resi- 
dent waveform data structures. The df_to_wf() function lets you read 
the data array (no scaling, offset, units, or titles) from a user-defined 
file format. The wf_to file() and wf to _afile() functions provide a 
means to write this data back out to disk (in ADIF format). For a com- 
plete description of ADIF, see Appendix E in the SPD Reference 
Manual. 


Program fragments in Sections 5 and 6 demonstrate how acquired data might be 
converted to a waveform data structure and then stored in a waveform file. 


Installation for GPIB Waveform Acquisition 


If you are going to acquire waveforms from instruments on the GPIB, you need 
to have the following hardware and software installed in your PC: 


@ The Tektronix GURU II hardware/software package, or 


@ The National Instruments GPIB-PCII, or GPIB-PCIIA hardware and 
software. 


Make sure that the GPIB.COM and IBCONF.EXE files are installed as 
directed in the manual that comes with the package. You must also make sure 
to add the line 

DEVICE=C: \path\to\driver\GPIB.COM 


to your CONFIGSSYS file. 
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Configure your GPIB board using IBCONF.EXE, as follows: 


@ The board device name should be set to GPIBO. Automatic Serial Poll- 
ing must be disabled for GPIBO. 


@ At least one device in the GPIBO device map should have a name be- 
tween DEVO and DEV16, or between TEKDEV1 and TEKDEV3. 


To be used with SPDMENUJ, your instrument should be set up as follows: 


@ The instrument’s address must be in the range 0 - 29. Address 30 is 
reserved for the controller. 


@ The instrument must be in T/L (Talker/Listener) mode. 


@ Message termination must be set to EOI. 


NOTE 


SPDMEWNU can access only one instrument of a given model (e.g., 
2430) if you are using the POLL address option. If you have mul- 
tiple devices of the same type, be sure to specify the actual address 
of the device you want, or SPDMENU always selects the one with 
the lowest address. 


Data Acquisition and the Menu Program @ 


Besides acquiring data from files, the SPDMENU Program contains built-in 
drivers for the Tektronix 2220, 2221, 2230, 2430, 2430A, 2432, 2440, 5223, 7D20, 
7912AD, 7912HB, 11401, 11402, RTD710, and RTD710A digitizers. Other 
drivers may also be available. Check the README.DOC file on disk 1 (if any) 
for the latest additions. Also, an acquisition program may be invoked while run- 
ning the SPDMENU Program (at a menu command entry point) by using the 


following command sequence: 
!<DOS command> 
For example: 


!acquire acq.wav 


ACQ.WAV. This file may then be read by the SPDMENU Program. In addi- 
tion, the SPDMENU Program has an acquire form available that permits run- 
ning the acquisition program and reading in the resulting file in one step. On 
disk 7 is the put2430 driver, which can be used to send a waveform to a 
Tektronix 2430, 2430A, or 2440. 


causes the program "acquire" to deposit acquired data in the file named @® 
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SPDMENU 
Tutorial 


SPDMENU is a menu-driven user interface to almost all of the SPD functions. 
It provides a way to do sophisticated signal processing without having to write a 
program. If you are a more advanced user you can also run your own special- 
ized code from within SPDMENU. 


Starting SPDMENU 


If you have installed SPD as indicated in Section 2 and the \TEK\SPD\MENU 
directory is in your PATH, you can invoke SPDMENU by typing: 


spdmenu 


If your screen does not display the initial SPDMENU screen, locks up, or dis- 
plays an error message and returns you to the DOS prompt, it is probably due to 
an installation error. Check Section 2, Getting Started for help. 


If all is well, SPDMENU will come up on the screen, and prompts will appear to 
help you perform data acquisition, signal generation, and signal processing. Con- 
text-sensitive help messages, available by pressing function key F1, and the 
keyboard overlay for the function keys provide on-line assistance as you move 
between the menus and forms. 


WAVEFORMS and SPDMENU 


Using SPDMENU consists performing of a series of actions on memory struc- 
tures called WAVEFORMS. Throughout this section, the capitalized word 
WAVEFORM refers to one of those memory data structures. The 
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WAVEFORM is designed to hold all of the data needed to represent an analog 

signal including the data array, title, units, scaling information, and an optional 
measurements string. A WAVEFORM name is a string of up to 10 characters, 
beginning with an alphabetic character. The WAVEFORM structures are 

named by you when you fill in a SPOMENU form that creates them, and they 

retain that name until they are deleted or you terminate SPDMENU. S 
WAVEFORMS are filled with data in several ways. They can be: 


@ read in from disk 
@ acquired from a Tektronix digitizer 


@ created by a signal generation function such as sine-wave or 
Squarewave. These are especially useful for learning and experimenting 
with the SPD package and for debugging procedures. 


@ created as the output of a function such as an FFT or an arithmetic 
function performed on one or more inputs WAVEFORM Structures. 


You can re-use a WAVEFORM structure, but each time you do, its former con- 
tents will be lost unless you copy it to another WAVEFORM first or save the 
WAVEFORM to disk. 


The data formats that SPDMENU can read include the ADIF format 

(described in Appendix E) from the READ menu and user-defined formats 

from the UREAD menu. The UREAD menu only reads in the actual data array © 
from the file. Scaling factors, offsets, units strings, etc. can be added manually 

from the EDIT menu. On the other hand, ADIF files can contain a full descrip- 

tion of a WAVEFORM. SPDMENU can read in these full descriptions without 

the manual intervention needed for user-defined formats. If you have saved 
WAVEFORMS generated by an earlier version of SPD, the ADIFGEN utility 

can be used to convert that file to the new ADIF format. 


Up to twenty WAVEFORMS can be resident in memory at one time (depending 
on the size of the WAVEFORMs and the memory available). Additional 
WAVEFORMS should be stored as WAVEFORM files. SPDMENU is an over- 
laid program so that the maximum possible memory can be dedicated to 
WAVEFORM structures, but you should also make sure that any unnecessary 
device drivers and memory resident software are removed from memory before 
invoking SPDMENU. 


subscripts into the WAVEFORM’s data array. Because they are not stored in 
memory as data values, they are also referred to as implicit. Sets of data that 
are explicitly stored in the WAVEFORM’s data array are called tuples. 


In SPD, the term dimension is used to describe a set of values that are actually ® 
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For example, if we created a WAVEFORM that represented temperature and 
humidity as floating point values at various points in a room, the three dimen- 
sions of the data array, X, Y, and Z (being only sets of subscripts into the data 
array) are three SPD dimensions, while the temperature and humidity values 
(being actual data values in the data array) are two SPD tuples. Because dimen- 
sion data have offsets and scaling factors, their values are often expressed as 
floating point numbers on a graph, but before being scaled for display they are 
merely subscripts. 


Actually, All WAVEFORMS used in SPDMENU (except acquired XY format 
and envelope WAVEFORMS) consist of a single dimension (X) and a single 
tuple (Y) of single or double precision floating-point data. You can select which 
data precision to use from the settings form. The default is single precision. 


Envelope WAVEFORMS have two Y values per X value (two tuples) but only 
the first is processed by the signal processing routines. XY format 
WAVEFORMs have explicit X and Y values as tuples. Only the values in the 
first tuple of a WAVEFORM can be processed by SPDMENU. The second Y 
trace of an envelope WAVEFORM and the Y values of an XY format 
WAVEFORM can be processed by user written code invoked through the 
process form. The input functions convert disk file data to the selected internal 
format. 


The SPD functions can handle more complex WAVEFORM formats than these, 
but if you need these complex formats you will have to write your own programs 
using ’C’ or QuickBASIC. See Sections 5 and 6 for more information on writing 
your own programs. 


WAVEFORM Attributes 


Besides the data array, WAVEFORMs have attributes associated with them. 
The attributes are: 

Title 

Measurement annotation strings 

Horizontal units 

Vertical units 

Horizontal scale factor 

Horizontal offset 


Vertical scale factor 


Vertical offset 
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A WAVEFORM title is a string of up to 20 characters. The title is displayed on 
the screen or output device when the WAVEFORM is graphed. 


Measurement annotation strings are attached to the WAVEFORM when 
measurement functions are used—they contain the measurement results. Only 
one measurement string at a time is associated with a WAVEFORM by 
SPDMENU. If an old string is present when a measurement function is in- 
voked, it is deleted to make room for the new measurements. 


All mathematical operations performed under SPDMENU combine the 
horizontal units, vertical units, and the horizontal scale factor in a manner consis- 
tent with the operation performed on the WAVEFORM data. Please note that 
this units processing is part of SPDMENU and not a part of the signal processing 
library. This means that units processing will NOT be automatically applied to 
your own QuickBASIC or ’C’ programs. 


WAVEFORM attributes are stored along with the WAVEFORM data when 

the WAVEFORM is written to a file, and are retrieved when the WAVEFORM 

is read back. The WAVEFORM name is not stored or retrieved but is con- 

verted to and from the file name by adding or removing a file extension string. 

If you don’t like the mapping between WAVEFORM names and file names, you 

can override the default names produced by SPDMENU. You can also change 

the default file extension using the settings form. -_ 


Graphing Capabilities 


Graphs of WAVEFORMS generated as a result of any operation are automati- 
cally displayed on the screen, unless automatic graphing is turned off from the 
settings form. Graphs appear in the lower half of the screen and consist of 
either one or two graphs depending on whether the operation generates one or 
two WAVEFORMs. (Whole screen display is available under the graph 
WAVEFORMs form, as is graphics output to other devices, such as printers or 
plotters.) 


Using SPDMENU 


SPDMENU has three levels of user interaction: @ 


@ the Main Menu is used for selecting the general type of operation to be 
performed. Typing the name or number of an entry in the main menu 
will lead you to a sub-menu. 
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@ Sub-menus are used for selecting the specific operation desired. When 
you select a sub-menu by typing its name or number, you are presented 
with a form. 


@ Forms are fill-in-the-blank screen interfaces used for specifying various 
parameters for the function you have chosen. After filling in the fields 
of a form, pressing the F2 function key causes the function to be ex- 
ecuted. 


If you know in advance the name of the form you need, you can bypass the main 
menu and sub-menus by typing the name of the form that you need. Actually, 
typing just enough of the name to be unique gets you to the correct form. If you 
are at the main menu or a sub-menu, simply type the form name. If you are al- 
ready in a form, pressing the F8 function key causes a prompt to appear at 
which you can type the name of the form you want. This kind of navigating 
bypasses the hierarchical menus and speeds up the use of SPDMENU after you 
are familiar with its facilities. For example, under the disp submenu there are 
several functions listed. One of those functions is graph WAVEFORMs. The 
graph WAVEFORMS function may be selected from any menu by entering: 


gra<Enter> 


To select the last menu (not form), press function key F4. To get back to the 
main or top menu, press F3. 


When transferring between forms, the fields you have filled out in the first form 
are "remembered" by SPDMENU even if you have not executed the function. 


The Screen 


The main menu, submenus, and forms all appear in the top half of the screen. 
Graphic output appears in the bottom half, unless full screen output is specified. 
WAVEFORM parameter measurement values, if present, appear to the left of 
the displayed WAVEFORM 
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Figure 3-1 shows the general layout of the screen. 


[spdmenu] - TEK Signal Processing and Display V2.2 HELP LEVEL = [2] 
1 Vaveforn Generation 
Acquisition, File 1/0, User Process 
Measurements 
Signal Processing 
Vaveform Arithmetic 
Complex Arithmetic 
Display Information 
Control 


Commands: [1-8 menu-name help quit Fi-Help F3-Top F4-Prev ?¢(Esc)] 


Fig. 3-1. General screen layout. 


The Main Menu 
The top or main menu lets you choose from the following sub-menus: @ 
gen WAVEFORM generation for generating standard 
WAVEFORMs 
i0 I/O for storing and retrieving files, acquiring 
WAVEFORMs, and invoking user programs 
meas Measurements for measuring various WAVEFORM 
parameters 
sig Signal Processing for performing various signal process- 
ing Operations 
arith WAVEFORM Arithmetic for performing commonly 
used mathematical operations 
complex Complex WAVEFORM Arithmetic for performing 
mathematical operations on complex WAVEFORMs 
disp Display Information for displaying and editing 
WAVEFORMS and associated data 
control Control for changing the mode settings such as auto- rd 


graphing, default directory, etc. 


The menus and forms that these selections lead to are specified in detail in Sec- 
tion 4. 
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SPDMENU Program Help 


SPDMENU includes an on-line help facility. There are three levels of help: 


@ level 0 provides a short command prompt line. 
@ level 1 lists the available commands 


@ level 2 (the default) lists available commands and also displays addition- 
al help text from the help files on the disk. 


To change the level of help, type: 
help = <0, 1, or 2><Enter> 
When the help level is 0 or 1, typing: 
help<Enter> 
displays a single line of help text. When the help level is 2, typing: 
help<Enter> 
displays one or more screens of text about the currently displayed menu or form. 
Typing: 
help <menu number>< Enter> 


displays one or more screens of help text about the appropriate menu (or func- 
tion). As an example, if you’re in the main menu, typing : 


help 4<Enter> 
at help level 0 or 1, displays the following: 
The sig menu contains the functions for signal processing. 


This indicates that submenu 4 contains functions performing signal processing 
operations. Note that typing help sig would produce the same result. 
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Menu Commands 


Table 3-1 lists and describes commands available from the menus. 


Table 3-1 
MENU COMMANDS ®@ 
Command Purpose 
F1 or help<Enter> Displays help text for current menu 
help number< Enter> Displays help for specified menu or 
or function 


help name< Enter> 


F3 Main (top) menu 

F4 Previous menu 

<menu or function name> Skips to specified menu or form 
!<program name> <Enter> Jumps forward to specified item 
quit < Enter> Exits SPDMENU 


Escaping to DOS ® 


The DOS escape command "!" can be used to execute DOS commands as well 
as user programs. When you use this command, a new copy of COM- 
MAND.COM is invoked in the space left after SPDMENU, the graphics device 
drivers, any memory resident programs (not recommended), and memory resi- 
dent WAVEFORMS have been accounted for. For example, to find out how 
much space is available for WAVEFORMs, you can type the command 


!chkdsk 


If enough memory is available, the DOS chkdsk command is run, displaying the 
disk and RAM available for your use. If you need more space to type your com- 
mand than the default prompt gives you, entering the command 


help=0 


causes a minimal prompt to be used, giving much more room for long com- 


mands to DOS. ® 


If the COMMAND or external program that you specify does NOT run, it is 
probably because there is not enough memory left for the program or command 
to run. Try removing some memory resident programs or WAVEFORMSs 
from memory and re-execute the program or command. Failure of a program to 
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run can also be caused by the program not being in the current working direc- 
tory or a directory specified in your PATH. 


Table 3-3 lists and describes the remaining function keys. 


The function key overlay included with the SPD manual has the following layout: 


1 2 
Help Run 
Func. 
3 4 
Top Prev. 
Menu Menu 
5 6 
Back Fwd 
Form Form 


7 8 
Kill Menu 
Form Name 


SPD Menu (c) 1986 Tektronix, Inc. 


Fig. 3-2. SPD Function key overlay. 


Function Parameter Forms 


Operations carried out by SPDMENU are actually performed by a series of C 
functions. These functions require input parameters specifying exactly how the 
operation is to be carried out. For example, generating a sinewave requires that 
values be entered for frequency, amplitude, dc offset, sampling interval, number 
of points in the output WAVEFORM, etc. Each function has an associated 
form in which these parameters can be set. Some parameters are set to default 
values which can be accepted or modified. 
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Form Fields 


There are three types of fields in a form that you can set: 


WAVEFORM and also are used to specify filenames. 
String fields are identified by having string values al- 
ready in them or by blank fields. 


Strings These fields assign names, titles, and units to a ® 


Numbers These fields only accept a number. Numbers are 
entered as integer or floating point values (floating 
point uses normal computer notation such as 1.5e-3 
(.0015) and 7.5E2 (-750.0)). Number fields are iden- 
tified as containing default numerical values. Numbers 
are displayed with the minimum number of needed trail- 
ing zeros. The decimal point is omitted if not needed. 


Choice These fields are changed to pre-determined values by 
pressing any key except the <Enter>, function, or cur- 
sor keys. To select the value shown in the field, press 
<Enter> or the down-cursor. These fields are iden- 
tified by having all uppercase characters as values. (File 
names also contain all uppercase characters and should 
not be confused with choice fields). 


The following example shows the various fields of the sinewave generation form. © 


Sinewave Specification 

Output Uaveform: 
Waveforn Title: (Horizontal ) 
Number of Points: 256 

Sampling Interval: 1 

(Vertical) Horizontal Units: Sec 

Frequency: 6.64 
Amplitude: 6.5 
Baseline Offset: 8 Phase: @ 
Amplitude Units: Volts Phase Units: DEGREES 


Commands: [Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6é-Fud up dn /Field] 


Fig. 3-3. Sinewave generation form. 


Note that some fields contain default parameters. @ 


On the screen, the current field is highlighted in reverse video, showing where 
the parameter may be entered, and its maximum length. 
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This form contains all three types of fields. Table 3-2 lists and describes these 
fields. ; 


| Table 3-2 
SINEWAVE FORM FIELDS 
Field Description 
Output Waveform (string) for entering a WAVEFORM name 


Waveform Title (string) 


Amplitude Units (string) 


Horizontal Units (string) 


Number of Points (number) 


Sampling Interval (number) 


Frequency (number) 


Phase (number) 


Amplitude (number) 


Baseline Offset (number) 


Phase Units (choice) 


(must begin with an alphabetic charac- 
ter) 


for entering any desired text that fits 
in the field 


for entering any text desired (for some 
operations, SPDMENU understands 
Sec and Hz to be inverses of each 
other) 


for entering any text desired 


for specifying the number of 
WAVEFORM samples the output 
WAVEFORM will have 


for specifying the time (if the Horizon- 
tal Units are time) between the nth 
and (n + 1)th sample data point 


for specifying the WAVEFORM fre- 
quency in 1/(Horizontal Units) 

for specifying the initial Phase(ex- 
pressed in Phase Units) 

for specifying the peak amplitude (ex- 
pressed in Amplitude Units) 

for specifying the "DC" component (ex- 
pressed in Amplitude Units) 


for specifying one of DEGREES, 
RADIANS, or GRADS 


Navigating The Form 


Navigating a form is done with the <Enter>, up-cursor, and down-cursor keys. 
Using <Enter> or down-cursor selects the next field on the form. Using up-cur- 
sor selects the previous field on the form. The field where input will be entered 


is highlighted. 
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NOTE 


The "next" (or "previous”) field on the form may or may not be the 
field immediately below (above) the current field. "Next" may ap- 
pear to skip around the form--this allows you to move to the most 
commonly altered fields more quickly. Also note that while the 
"left" and "right" arrow keys might seem to make sense, they are 
not implemented with SPDMENU. 


Two search or "go direct" commands are provided that let you skip to a field 
without stepping through all the intervening fields: 


/<field name> searches for the specified field in a forward direction 


?<field name> searches for the specified field in a backwards direction 


To search for a specific field, enter the appropriate search command. The / or ? 
is displayed on the command line at the bottom of the form. Type enough of 
the field name to be unique and press: 


<Enter> 

The desired field is then highlighted. 

For example, to skip to the "Phase Units” field, type: 
/Phase u< Enter> 


Note that upper or lower case is not important; e.g., U and u are the same. The 
field name is remembered after the first invocation, so to skip to the next field 
having a similar name (e.g., from Amplitude Units to Amplitude) type: 


/<Enter> 


Some functions have too many parameters to fit on one (half-screen) page. 
These forms have an informational field indicating the number of pages; e.g.,: 


"(Page 1 of 2)" 


To see the second page, press F5 or F6 (Fwd and Back). Use the same keys to 
return to the previous page. 


Changing a field sometimes results in automatic changes being made in other 
fields. This most often occurs when a Waveform Name field or Scaling Mode 
field (graph function) is changed. The automatic changes provide appropriate 
default values for the named WAVEFORM or chosen scaling mode. 
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Executing A Function 


Once all the parameters are set to the desired values, the function is executed by 
pressing the F2 key (labeled RUN). A "running" message is displayed on the 
screen, indicating that the function is executing. Unless specified in the Settings 
form (by setting Automatic Graphs to OFF), a graph of the resultant 
WAVEFORM is automatically displayed. 


IMPORTANT! 


A function is not automatically executed you must request the 
action. You can leave a form without executing the function. 


Values entered into a form are remembered by the program, and re-appear if 
the function is invoked again. Pressing the F7 (Kill Form) key instructs the 
program to ignore values entered into the form and automatically returns to the 
previous menu. 
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Form Commands 


6 


Table 3-3 lists and describes the form commands. 


Table 3-3 
FORM COMMANDS _ 
Command Purpose 
CTRL-U Delete new text entered in existing 
field 
CTRL-H Delete last character (same as back- 
space) 
CTRL-< back space> Clear current field 
Fl Display help text for form page 
F2 Execute function 
F3 Main (top) menu 
F4 Previous menu 
iS Next form page 
F6 Previous form page 
Ps Kill form © 
F8 <menu or function name> Skip to specified menu or form 
<Enter> or down cursor Next form item on current page 
up cursor Previous form item on current page 
/<item name> <Enter> Jumps forward to specified item 
?<item name> <Enter> Jumps backward to specified item 


The CTRL-U command (holding down the Ctrl key and pressing U) allows you 
to "Undo" the typing you have done in a field, thus restoring the old value your 
typing may have wiped out. 


If you actually want to blank out a field, type CTRL-< back space>; that is, 
press the back space key while holding down the Ctrl key. 


The Process Form ¢ 


The process form lets you run your own program on SPD. Up to four 
WAVEFORMs may be specified (one minimum). Each specified 
WAVEFORM is written to disk before processing with the user program, and is 
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read back into SPOMENU after processing. Whether the function of a 
WAVEFORM is input to, or output from your program, depends on your 
program. PROCESS.C and PROCESS.BAS are skeleton files provided on disk 
4. They should be used as a model for building your own user program. The 
process form may be used to: 


® access functions not in SPDMENU 
@ process the second Y trace of an envelope wave function 


® combine functions for user convenience, etc. 


After writing the WAVEFORMS you specify to the files you specify, 
SPDMENU invokes the program that you name with a command line contain- 
ing the names of all files that were written. (If no WAVEFORM name is 
specified, the file is not written.) After your program runs and control returns to 
SPDMENJ, the files that have WAVEFORMS associated with them are read 
back into memory. If the third and fourth WAVEFORMS were read in, they are 
graphed. Because of this, the third and fourth WAVEFORMS are usually used 
for results of the program invoked. You can skip WAVEFORM two, if neces- 
sary, to make the results of your external program appear in the third and fourth 
WAVEFORMs. 


The Driver Form 


The driver form lets you run external acquisition drivers such as PUT2430.EXE 
which is supplied with SPDMENU. You can also write you own acquisition 
drivers for instruments not supported by the built-in drivers. 
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SPDMENU - An Example 


This example shows how to use SPDMENU to transform a generated or ac- 

quired signal into the frequency domain and display it using the whole screen. 

You may wish to duplicate the following steps on your computer as you read the 
example. © 


Figure 3-4 shows the main menu.. 


Cspdmenu] -— TEK Signal Processing and Display V2.2 HELP LEVEL = [2] 
{ 1] gen Vaveform Generation 
io Acquisition, File 1/0, User Process 
meas Measurements 
sig Signal Processing 
arith Vaveform Arithmetic 
comp lex Complex Arithmetic 
disp Display Information 
contro] Control] 


Commands: [1-8 menu-name help quit Fi-Help F3-Top F4-Preyv ¢(Esc)] 


Fig. 3-4. The main menu. 6 
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Generating a Standard Waveform 


Select the Waveform Generation submenu by typing 1 or gen <Enter>. The 
Waveform Generation submenu is shown in Figure 3-5. 


Cgen] —- gen — Waveform Generation Functions HELP LEVEL = [2] 
1] sine 
square 
sinc sin(x)/x 
sin2 sine-squared pulse 
randb Binary Random 
gauss Gaussian Random 
unif | Uniform Random 


Commands: [1-7 menu-name help quit Fi-Help F3-Top F4-Prev ¢(Esc)] 


Fig. 3-5. The waveform generation submenu. 


Select sine by typing: 


© 1<Enter> 


The sinewave form is displayed. The parameters shown in Fig. 3-6 are the 
defaults that are set by SPDMENU. You can modify them, but this example 
uses the defaults. 


NOTE 


Once you are familiar with the names of the SPDMENU fonns, 
you can type the name of the form that you want to go to instead 
of working your way through the menus. In this case, typing "sine" 
at the top menu prompt will bring you right to the sinewave form. 
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Sinewave Specification 


Output Vaveform: 
Waveforn Title: (Horizontal ) 
Number of Points: 256 
Sampling Interval: 1 
(Vertical) Horizontal Units: Sec 
Frequency: 6.04 

Amplitude: 8.5 
Baseline Offset: 8 Phase: 8 
Amplitude Units: Volts Phase Units: DEGREES 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Fig. 3-6. The sinewave form. 


The only field that you must fill in to get a default sinewave is Output 
Waveform. This specifies the name of an in-memory WAVEFORM data struc- 
ture that SPOMENU uses to store the results of generating the sinewave. If you 
leave this field blank, SPDMENU displays an error message. Enter the name 
"s" for this Field. It is not necessary to specify a title, but for this example, enter 
the string "Sample Sine Wave" in the Waveform Title: field. 


Execute the function by pressing F2. A message is displayed indicating the ex- 
ecution status of the function. The WAVEFORM is automatically displayed as 
shown in Fig. 3-7. 


Sinewave Specification 


Output Vaveform: s 
Waveform Title: Sample Sine Wave (Hor izonta 1) 
Number of Points: 256 


Sampling Interval: 1 
(Vertical > Horizontal Units: Sec 
Frequency: 86.64 


Amplitude: 8.5 
Baseline Offset: 6 Phase: 8 
Amplitude Units: Volts Phase Units: DEGREES 


Commands: ([Fi-Help F2-Run F3-Top F4—-Prev FS-Back F6é-Fud up dn /Field] 
Sarmmple Sine Wave 


S\N le 


Fig. 3-7. Sinewave graph. 


3-18 Signal Processing & Display 


SPDMENU Tutonal 


Acquiring a Waveform 


Another way to get a WAVEFORM to work with, is to acquire one from a 
Tektronix digitizer. 


Assuming that you have installed a PCII or PCILA GPIB card in your computer 
and that at least one device name in the GPIB map is in the range DEVO - 
DEV16 or TEKDEV1 - TEKDEV3, you can then hook up a Tektronix 2430 
digitizing Oscilloscope, for instance, to your GPIB port and proceed as follows: 


From the main menu, select the io submenu by typing: 
2<Enter> 
or 
io<Enter> 


The following submenu will be displayed: 


Cio] - io — Acquisition, File 1/0, User Proce HELP LEVEL = [2] 
read — Read waveform from disk 
write -— Write waveform to disk 
uread -— Read User File 
process—- perform user process on waveforn 
driver — acquire or send waveform (external driver) 
acquire-——- acquire waveforns (built in) 


Commands: [1-6 menu-name help quit Fi-Help F3-Top F4-Prev !(Esc)] 


Fig. 3-8. The io submenu. 
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The menu choice for this example is: 


acquire<Enter> 


which presents a menu of built-in acquisition forms for Tektronix digitizers that 
looks like this: 6 


Cacquire] - acquire-—— acquire and send HELP LEVEL = [2] 
] get22260 — Acquire waveform 
getZ238 —— Acquire wavef orm 
getZ236@s-- Acquire waveform 
get2436 -- Acquire waveform 
get?7D268 — Acquire a waveform 
getS223 — Acquire waveform 
get114686— Acquire waveform 
getRTD -- Acquire waveforn 
get78S4 — Acquire a waveforn 
get7912 —— Acquire a waveform 

(1-18 menu-name help quit Fi-Help 


2438/2438A/2432/2448 
7D28 

5223 

11461/11482 


c 
C 
C 
C 
C 
C 
C 
C 
C 


Pewee oee ow 


7912AD/7912HB 
-Top F4-Prev !(Esc)] 


ee Re ee Ee ee 


Fig. 3-9. Acquisition form menu. 


From this list, choose the get2430 function by typing } 
get2430<Enter> 


which produces the following screen:. 


Acquire a 2436/2430A’2432/2446 waveform 


Waveform source: CHi1 


GPIB address: POLL 
Timeout: 30 SEC 


Normalize Data (Offset and Scale Factor)?: YES 


Commands: [Fi-Help F2-Run F3-Top F4-Preuv FS-Back F6-Fud up dn /Field] 


Fig. 3-10. 2430 Acquisition form. 
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Actually, typing get24 is unique enough to get to this form. If you knew in ad- 
vance that this was the form that you needed, you could have typed get2430 at 
the top menu and had the same results. 


Now, fill in the form by specifying the Acquired Waveform field as 
s < Enter> 


to use the same name as the sine wave generation option discussed earlier. If 
you generated the sine wave as WAVEFORM sg, before, executing this function 
over-writes the contents of that WAVEFORM. 


If you let all of the other fields remain at their default values, you will acquire 
from CH1, let SPDMENU find the address that the 2430 is connected to, 
timeout after 10 seconds, and the resulting WAVEFORM structure will be nor- 
malized; that is, the values in the data array are scaled and offset so that they 
represent Volts instead of Digitizer Levels. Of course, you can override these 
values but you will usually find that, with the exception of the Waveform source, 
the defaults are best. 


If you have more than one 2430 connected to the GPIB, using POLL as the ad- 
dress finds only the first one, so to find the other one(s), you will have to specify 
the address explicitly. 


Now press function key F2. The results should be similar to this: 


Acquire a 24360/24380A/2432/2446 waveforn 


Acquired Waveform: s 


aveform source: CH 


GPIB address: POLL 
Timeout: 3@ SEC 


Normalize Data (Offset and Scale Factor)?: YES 


Commands: (Fi-Help F2-Run F3-Top F4—Prev FS-Back F6-Fwd up dn “Field} 


ea eeomae eae CH1 DC 200mV Sms NORMAL 


Fig. 3-11. Acquired waveform. 
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Taking the Fast Fourier Transform 


To convert the generated or acquired WAVEFORM, s, to the frequency 
domain, you apply an FFT function to WAVEFORM. To get to the FFT form, 


press F8 to get a Menu prompt, and type © 


fft<Enter> 


You can also return to the top menu by pressing F3 and following the menus to 
the FFT form (in the sig sub-menu). 


There are two SPD functions that take the FFT of a WAVEFORM. The /ft() 
function requires both a real and imaginary WAVEFOR\M as input, while the 
fft() function takes a single, real WAVEFORM. The SPDMENU FFT form 

determines which function to use by whether you specify both inputs or only a 
real input. At the Input Real Waveform prompt, type 


s<Enter> 


Leave the Input Imaginary Waveform field blank, since there is no imaginary 
WAVEFORM to use. You also must specify real and imaginary outputs, so at 
the Output Real Waveform and Output Imaginary Waveform fields, type: 


r<Enter> _ 
and 
i<Enter> 


respectively. These will be temporary files, so no title is necessary. Leave the 
Output Waveform Titles field blank. When you press F2, SPDMENU allocates 
the space needed for the output WAVEFORMS automatically, and invokes the 
appropriate SPD function. If you want to call the 7/ft() or fft() functions from 
your own programs, you must create the output WAVEFORMS yourself. 
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When the function returns, the screen should display both of the output 
WAVEFORMS: 


Input Real Waveforn: s 
Input Imaginary Vaveforn: 
Output Real Waveform: r 
Output Imaginary Vaveform: i 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fwd up dn /Field] 
Creal) 


td Tell 


i 


} Fig. 3-12, Output waveform screen. 
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Converting the Results to Polar Form. 


Now, look at the results from a Polar viewpoint. Press F8 for a menu prompt, 
and type: 


polar <Enter> @ 


This brings up the Polar form. 


Fill in the Input Real Waveform and Input Imaginary Waveform fields with the 
results of the last operation, r and i. Label the output fields as mag and phase. 
Label the WAVEFORMs by entering 


Frequency Domain< Enter> 


in the Output Waveform Title field. Leaving the other fields at their default 
values, press F2 to generate the Polar representation of the FFT. The display 
should look like this: 


Polar Specification 


Input Real Vaveform: r 
Input Imaginary Waveform: i 
Output Magnitude Waveform: mag 
Unwrap Phase: FALSE Output Phase Waveform: phase 
Phase Units: DEGREES 
Delay Adjustment: 8 Dutput Waveform Title: Frequency Domain 


: C€Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6-Fwd up dn “Field] 


Frequemcy Dornain (rnag) 


2 ° / sec 


Frequency “omain (Cohase) 


Fig. 3-13. Polar representation of the fft. 
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Note that SPDMENU has added (Mag) and (Phase) to the titles of the two 
WAVEFORMS just as it created (Real) and (Imag) titles for r and i. 


Controlling the Graphics Options 


Now, take a closer look at the mag WAVEFORM. Press F8 for a menu prompt 
and enter 


gr<Enter> 


This is sufficient to bring up the Graph form, which allows you to control the 
graphic representation of WAVEFORMS on your screen. At the Waveform 1 


prompt, type 
mag < Enter> 


When you press <Enter>, the minimum and maximum values on both the X 
and Y axes are displayed in the form which looks like this: 


Graph Vaveforn 
(Page 1 of 2) 
Vaveform 1: mag Vaveform 2: 


~axis: LINE X-axis: 
Y-axis: LINEAR 
Scaling: 

X-min: 

X—max : 


Y=nin: 
Yrmax : 
Commands : [Fi-Help F2-Run F3-Top Fa-Prev FS PS Back F6-Fed up dn Field) 


Frequemcy Dornain (rnag) 


Nl 


Poaamen Dorncin Cophnase) 


Fig. 3-14. Graph form with Mag waveform. 


Note that the Fields labeled X-AXIS and Y-AXIS both have the value 
LINEAR. By positioning the field cursor over these values and pressing the 
space bar, the value changes to LOG. When you press F2, the axes that have 
been set to LOG are displayed with logarithmic scaling. This does not change 
the values in the WAVEFORM structure as the LOG function does; it only af- 
fects the display. 
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When you change the axis type from LINEAR to LOG or back again, the maxi- 

mum and minimum values change to reflect the new scale. If you change the 

value of the the Scaling field from AUTO to MANUAL by positioning the cur- 

sor and pressing the space bar, then you can enter new minimums and maxi- 

mums for either axis. These new limits are used when you re-draw the graph (by 

pressing F2). This is the way to zoom in (or out) on a graph with SPDMENU. © 


Centered at the top of the Graph form is the statement "(Page 1 of 2)". When 
you press F6, the second page is displayed. Pressing F5 returns the display to 


page 1. 


On page 2 of the form are several important fields. These are all choice fields, 
so you can change their values by positioning the field cursor over them and 
pressing the space bar. 


The top field, labeled "Destination", controls where SPDMENU directs the 
WAVEFORM graph. The default value is SCREEN, which causes the graph to 
appear below the menu. Selecting WHOLESCREEN causes the graph to fill 
the entire screen, replacing the menu. When this occurs, pressing any key re-dis- 
plays the menu. 


The other two choices, PRINTER and PLOTTER, direct the graphics output 

to the currently loaded printer or plotter driver. If you did not install a printer 

or plotter driver from your CONFIG.SYS file at boot time, selecting one of © 
these options generates an error when you execute the graphing function (by 

pressing F2). 


The Grid Style field allows you to specify a dotted grid, a solid grid, or no grid at 
all (the default). 


You can modify the Line Style field to select one of many line styles such as 
solid, dashed, etc. SPDMENU offers an interpolated line style which may make 
your display easier to read. In addition, the MARKERS selection from this field 
replaces a continuous line with a marker at each data point. 


The last four fields allow you to specify the color to be used for axis, curves, text 
and the background of the display. 
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Here isa WHOLESCREEN display of the mag WAVEFORM with a LOG Y 
axis. 


Frequency Domain (mag) 


Fig. 3-15. WHOLESCREEN display of Mag waveform. 


The selections that you make on this screen are remembered until you change 
® them or you leave SPDMENU. 


More Details 


You can find more details on the SPDMENU menus and forms in Section 4, 
SPDMENU Reference. 
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Section 4 


SPDMENU 
Reference 


This section presents detailed information about the use of SPDMENU. Section 
3 is a tutorial for new users. 


The SPDMENU Menus and Forms 


The following pages display each menu and form of SPDMENU. Below the 
form is an explanation of the fields in the form. This information can be found 
online by pressing the Fl key when SPDMENU is located at that menu or form. 


The menus are presented first in hierarchical order starting with the main menu. 
Browse the menus when you need to find a particular form that meets your 
needs. 


The forms come next, in alphabetical order. The change in order is for two 
reasons. First, it makes it easier to find a form when you know its name. It also 
emphasizes that you don’t have to follow the menu Structure to get to a form. 
From any menu prompt, including the prompt generated by pressing < F8> 
from within a form, typing the name of ANY form will bring you right to that 
form. 
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MAIN Menu 


[spdmenu] — TEK Signal Processing and Display V2.2 HELP LEVEL = [2] 
1] gen Vaveform Generation 
io Acquisition, File 1/0, User Process 
neas Measurements 
sig Signal Processing 
arith Vaveform Arithmetic 
comp lex Complex Arithmetic 
disp Display Information 
contro! Control 


Commands: [1-8 menu-name help quit Fi-Help F3-Top F4-Preyv *(Esc)] 


NOTE: 


<Enter> means press the key marked "Enter". The same ts true 
for the function keys. 


At the "Command:" prompt you can 


Type: digit < Enter> The digit should correspond to one of the 
digits displayed in brackets. If the entry is © 
the name of a submenu, that submenu is dis- 
played. If the entry is the name of a func- 
tion, the form for that function is displayed 
(there is at least one exception-- Names; it is 
executed directly). 


Type: name < Enter> of a sub-menu or function (it need not be 
currently displayed) followed by <Enter>. 


This has the same effect as typing the cor- 
responding number. 


Press: <F1> Display this help file. 


Type: help = n<Enter> Where n is 0 or 1 or 2. This sets the help 
"level" which controls how much information 
is available with the "Command" prompt and 
the amount of information you’ll see when 
you request help. 


Type: help n: Displays help information about the item r 
marked by the digit "n". 


Press: <F3> Takes you to the top menu level. 


Press: <F4> Takes you to the previous menu. 
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Type: !1DOS COMMAND Temporarily escapes from SPDMENU and 
executes the requested DOS command. 
When the command has completed, press 
<Enter> to continue with SPDMENU. 
Warning--this activity takes some memory. If 
the command seems to do nothing, you're 
probably out of memory. <Enter> gets you 
back to SPDMENU. 


Type: quit <Enter> Quits SPDMENU and returns to DOS. 


Form Fillout: When you first enter a form, some of the fields may already con- 
tain data. These are "default entries". In some forms, once you reference a 
waveform, some additional data is filled in according to the data that’s in that 
waveform. You can change it, though. Later, when you return to the form, 
you'll find the data as you left it (unless there have been changes to the 
referenced waveform; in that case, the data reflects those changes). 


The current field is the one that’s highlighted. The extent of the highlight shows 
how long the field is allowed to be. In general, to add or change data in a field, 
just type. Your new data overwrites anything that might already be there. You 
may backspace to correct typing mistakes or type <ctrl> <u> which erases 
everything you’ve entered in the field and allows you to start over. Finish enter- 
ing data in a field, with <Enter>. That also advances you to the next field. 

You may also signal completion by pressing a function key. Typing over the end 
of a field will also carry you to the next field. 


There are three kinds of fields: 


Strings: e.g. waveform names, title strings, units strings, file names, etc. Blanks 
are permitted (although DOS might object if you put one in a file name). You 
can clear a string field by typing <ctrl> <Backspace>. (Press and hold the key 
marked "Ctrl", press and release the Backspace key, release <ctri>. 


Numbers: e.g. 100.5 or 1.005e2. If a number is supposed to be an integer, any- 
thing entered after a decimal point will be ignored. 


Toggles: These are indicated by default values shown in capital letters. Cycle 
through the choices by pressing the space bar. You can’t type anything into 
these fields. 


In a form you can 


Press: <Enter> Advance to the next field. 

Press: <2> (down arrow key) Advance to the next field. 
Press: <8> (up arrow key) Go to previous field. 

Press: <F1> Get help information about the form. 
Press: <F2> Run the function with the data shown. 
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Press: <F3> Leave the form and go to the top menu. 
Press: <F4> Leave the form and go to the previous menu. 
Press: <F5> Go back to the previous page of the form (a 
few have more than one page). ® 
Press: <F6> Advance to the next page of the form. 
Press: <F7> Ignore changes made to the form and go to 


the previous menu. 


Press: <F8> Name Leave the form and go directly to the form 
or menu called "Name". 


/String: Go to the next field whose name begins with 
"String". This only works before you start 
entering data in a field. 


NOTE 


You must run the function (by pressing <F2>) to make anything 
happen. Leaving the form does NOT cause execution of the func- 
tion. 
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GEN Menu 


[gen] - gen — Waveform Generation Functions 
1] 
E 2] 
C 3] 
{ 4] 
[ 
C 
[ 


5] 
6] 
7] 


sine 


square 


sinc 
sin2 
randb 
gauss 
unif 


Commands: [1-7 menu-name help quit 


HELP LEVEL = [2] 


sin(x)/x 
sine-squared pulse 
Binary Random 
Gaussian Randon 
Uniform Random 


Fi-Help F3-Top F4-Prev ¢(Esc)] 


The gen menu includes commands for generating, copying, and editing 


waveforms. 


Signal Processing & Display 


SPDMENU Reference 


lO Menu 


— Acquisition, File 1/0, User Proce HELP LEVEL = [2] 
read — Read waveform from disk 

write -—— Write waveform to disk 

uread -—— Read User File 

process— perform user process on waveform 

driver — acquire or send waveform (external driver) 
acquire——- acquire waveforms (built in) 


Commands: [1-6 menu-name help quit Fi-Help F3-Top F4-Prev ?(Esc)] 


The io menu contains commands for reading and writing waveform data to and 
from disk files. 
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ACQ Menu 


waveforms HELP LEVEL = [2] 
waveform from Tek 2226/2221 
waveform fron Tek 2238 
waveform from Tek 2238 (RS2Z32) 
waveform fron Tek 2438/2436A/2432/2448 
waveform from Tek 7D28 
waveform fron Tek S223 
waveform from Tek 11401/11482 
waveform from Tek RTD71@ 
get78S4 -- Acquire waveform from Tek 7854 
get7912 -—— Acquire waveform from Tek 7912AD/7912HB 
: [1-18 menu-name help quit Fi-Help F3-Top F4—Prev ¢(Esc)] 


getZ226 —- Acquire 
get2238 — Acquire 
getZ223@s-—- Acquire 
get2438 — Acquire 
get?7D26 -—- Acquire 
getS223 — Acquire 
get114@8—-— Acquire 
getRTD -- Acquire 


seen ep w 
ee 


The acq menu contains commands for sending and acquiring waveform data to 
and from Tektronix digitizers. 
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MEAS Menu 


[meas] - meas — Measure Waveform Parameters HELP LEVEL = [2] 
{C 1] mpulse 
{C 2] mstats 
{ 3] sinemeas 


Commands: (1-3 menu-name help quit Fi-Help F3-Top F4-Prev ¢(Esc)] 


The meas menu contains functions for performing measurements on waveform 
data. 
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SIG Menu 


Csig] - sig —- Process Waveform Data HELP LEVEL = [2] 
fft 

ifft 

int 

diff 

decin 

interp 

taper 

corr 

conu 


c 
C 
C 
C 
C 
C 
C 
C 
C 


Commands: [1-9 menu-name help quit Fi-Help F3-Top F4—-Prev ¢(Esc)] 


The sig menu contains the functions for signal processing. 
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ARITH Menu 


Carith] - arith — Waveform Arithmetic Functions HELP LEVEL = [2] 
add 
sub 
div 


C 
c 
C 
C 
C 
C 
C 
C 
C 


C186] sqrt 
Commands: [1-18 menu-name help quit Fi-Help F3-Top F4-Prev ¢*(Esc)] 


The arith menu contains functions for performing arithmetic on waveforms. 
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COMPLEX Menu 


Ccomplex] -— complex — Complex Waveform Arithmetic HELP LEVEL = [2] 
cpxadd 

C cpxsub 

[ cpxdiv 

C cpxnmu It 

[ 

C 


polar 
rect 


Commands: [1-6 menu-name help quit Fi-Help F3-Top F4—Prev ¢(Esc)] 


The complex menu contains functions for performing complex arithmetic on 
waveforms. 
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DISP Menu 


(disp] - disp — Display Waveform Information HELP LEVEL = [2] 
{ 1] graph waveforns 
{[ 2] names of waveforms 


Commands: [1-2 menu-name help quit Fi-Help F3-Top F4-Prev ?(Esc)] 


The disp menu lists commands for displaying data. 
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CONTROL Menu 


(control) - control — Control System Behavior HELP LEVEL = [2] 
{ 1] settings for this program 
{ 2] edit waveforn 
{ 3] copy waveforn 
{ 4] delete waveform 


Commands: [1-4 menu-name help quit Fi-Help F3-Top F4-Prev ¢*(Esc)] 


The control menu contains functions for controlling defaults together with some 
miscellaneous functions. 
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ADD Form 


Add Specification 


nput Waveform: 
<Input Waveform or double const>: 


Output Waveform: 
Output Vaveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /“Field] 


Input Waveform: Enter the name of an existing waveform. 
<Input Waveform or double An existing waveform name or a number. 
const>: Both input names can be the same. 
Output Waveform: Enter the name of the waveform that will 


contain the sum. If it doesn’t already exist, 
it will be created. You can use the same 


name as for input. ® 


Output Waveform Title: Enter a title (optional). 


For more detail, see the w_add and we_add functions in Section 8. 
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CONV Form 


Convolution Specification 


nput Waveform: 
Input Vaveform: 


Output Vaveform: 
Output Waveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the names of the waveforms to be con- 
volved. 

Input Waveform: Both must exist. 

Output Waveform: Enter the name of the waveform that will 


contain the convolved data. If it doesn’t al- 
ready exist, it will be created. You can NOT 
use the same name as for input. 


Output Waveform Title: Enter a title (optional). 


For.more detail, see the fconv function in Section 8. 
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COPY Form 


Copy Vaveform Specification 


Subsection Start: 8 
Subsection End: 6 


Output Waveform: 
Output Waveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform: Name the source waveform. It must already 
exiSt. 
Subsection Start: The point at which to start the copy 
(horizontal units). 
Subsection End: The point at which to end the copy (horizon- 
tal units). 
Output Waveform: Enter the name of the waveform that will ® 
contain the output data. If it doesn’t already 


exist, it will be created. 


Output Waveform Title: (Optional) The string will be displayed at 
top of graph. 


For more detail, see the the zone_dim and copy wf functions in Section 8. 
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CORR Form 


Correlation Specification 


8 
Input Vaveforn: 


Output Vaveform: 
Output Waveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the names of the waveforms to be cor- 
related. 

Input Waveform: Both must exist. Both may be the same 
name (auto-correlation) or different (cross 
correlation). 

Output Waveform: Enter the name of the waveform that will 


contain the output data. If it doesn’t already 
exist, it will be created. You can NOT use 
the same name as for input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the fcorr function in Section 8. 
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CPXADD Form 


Add Complex Specification 


Rea nput Waveforn: 

Imaginary Input Waveforn: Real Output Waveform: 
Imaginary Output Waveform: 

Real Input Waveforn: Output Waveform Title: 

Imaginary Input Waveform: 


Commands: [(Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /“Field] 


Real Input Waveform: Enter the name of an existing waveform. 
Imaginary Input Waveform: Enter the name of an existing waveform. 
Real Input Waveform: Enter the name of an existing waveform. 
Imaginary Input Waveform: Enter the name of an existing waveform. 


Real Output Waveform: Enter the name of the waveforms that will 

Imaginary Output Waveform: contain the sums. If they don’t already exist, @ 
they will be created. You can use the same 
names as for input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the cpx_add function in Section 8. 
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CPXDIV Form 


Div Complex Specification 


Hea nput Waveforn: 

Imaginary Input Waveform: Real Output Waveform: 
Imaginary Output Waveform: 

Real Input Waveforn: Output Waveforn Title: 

Imaginary Input Waveform: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Real Input Waveform: Enter the name of an existing waveform. 
Imaginary Input Waveform: Enter the name of an existing waveform. 
Real Input Waveform: Enter the name of an existing waveform. 
Imaginary Input Waveform: Enter the name of an existing waveform. 


Real Output Waveform: Enter the name of the waveforms that will 

Imaginary Output Waveform: contain the quotients. If they don’t already 
exist, they will be created. You can use the 
same names as for input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the cpx_div function in Section 8. 
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CPXMULT Form 


Mult Complex Specification 


Rea nput Wavetorn: 

Imaginary Input Waveforn: Real Output Waveform: 
Imaginary Output Waveform: 

Real Input Waveforn: Output Waveform Title: 

Imaginary Input Vaveforn: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Real Input Waveform: Enter the name of an existing waveform. 
Imaginary Input Waveform: Enter the name of an existing waveform. 
Real Input Waveform: Enter the name of an existing waveform. 


Imaginary Input Waveform: Enter the name of an existing waveform. 


Imaginary Output Waveform: contain the products. If they don’t already 
exist, they will be created. You can use the 
same names as for input. 


Real Output Waveform: Enter the name of the waveforms that will ® 


Output Waveform Title: Enter a title (optional). 


For more detail, see the cpx_mult function in Section 8. 
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Sub Complex Specification 


is a 

Imaginary Input Waveform: Real Output Waveform: 
Imaginary Output Waveform: 

Real Input Waveforn: Output Waveform Title: 

Imaginary Input Waveform: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Real Input Waveform: Enter the name of an existing waveform. 
Imaginary Input Waveform: Enter the name of an existing waveform. 
Real Input Waveform: Enter the name of an existing waveform. 


Imaginary Input Waveform: Enter the name of an existing waveform. 


Imaginary Output Waveform: contain the differences. If they don’t already 
exist, they will be created. You can use the 
same names as for input. 


e Real Output Waveform: Enter the name of the waveforms that will 


Output Waveform Title: Enter a title (optional). 


For more detail, see the cpx_sub function in Section 8. 
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-DECIM Form 


Decimation Specification 


Decimation Factor: 4 


Output Vaveform: 
Output Waveform Title: 


Commands: [(Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the name of the waveform to be 
decimated. It must already exist. 


Decimation Factor: Integer factor to decimate the waveform, 
i.e., every "factor"th data item will be kept, 
starting with the first data item in the 
waveform. A "contraction" factor. 


Output Waveform: Enter the name of the waveform that will 
contain the decimated data. If it doesn’t al- 
ready exist, it will be created. You can NOT 
use the same name as for input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the w_decimate function in Section 8. 
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. DELETE Form 


Delete Waveform Specification 


Waveform to delete: 


Commands: [Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6-Fud up dn /Field] 


Waveform to delete: Name the waveform to be deleted. 


NOTE 


Use the NAMES function to list the names and sizes of currently 
existing waveforms. 


@ For more detail, see the free_wf function in Section 8. 


Signal Processing & Display | 4-23 


SPDMENU Reference 


DIFF Form 


Differentiation Specification 


End-of-frray: REPEAT 
Differentiator Length: 2 


Output Vaveforn: 
Output Waveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn “Field] 


Input Waveform: Enter the name of the waveform to be dif- 
ferentiated. It must already exist. 


End-of-Array: How to substitute for data beyond the ends 

of the array. 
Differentiator Length: Length of the differentiator impulse 

response (integer). ® 
Output Waveform: Enter the name of the waveform that will 


contain the differentiated data. If it doesn’t 
already exist, it will be created. You can use 
the same name as for input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the diff function in Section 8. 
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DIV Form 


Div Specification 


a 
<Input Waveform or double const>: 


Output Waveform: 
Output Waveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fwd up dn /Field] 


Input Waveform: Enter the name of an existing waveform. 
<Input Waveform or double An existing waveform name or a number. 
const >: Both input waveform names can be the same. 
Units: Divisor units (this field only has significance 


when the field above contains a number). 


Output Waveform: Enter the name of the waveform that will 
contain the quotient (first/second). If it 
doesn’t already exist, it will be created. You 
can use the same name as for input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the w_div and we_div functions in Section 8. 
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DRIVER Form 


Run Acquisition Program Specification 
Program Name: ACQUIK 


Waveforn File Name: 
IO Function: READ 


Waveform Name: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Program Name: The name of the acquisition program, includ- 
ing path. If the program takes command 
line switches, they can be entered here. 


Waveform File Name: Enter the file name that the acquisition 
program creates or reads. Include path in- 
formation if the file is not in the current 
directory. (Also, see the SETTINGS Form.) & 


IO Function: READ or UREAD: the file will be read 
using the associated SPDMENU function. 
If UREAD, make sure the settings of the 
UREAD Form are appropniate to the for- 
mat of the acquisition program’s output file. 


Waveform Name: The Waveform Name will be created 
automatically when you specify the 
Waveform File Name, but you can change it. 
If it doesn’t already exist, it will be created. 
After running your program, the file will be 
read using the specified IO Function and dis- 
played. 
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EDIT Form (Page 1) 


Edit Waveform Characteristics Specification 
(Page i of 2) 
Waveform: 
Sampling Interval: 1 Horizontal Value: 8 
Sample Point Number: @ Amplitude: @ 


Vertical scale factor: 8 
Vertical offset: 8 Horizontal offset: @ 


Normalize Data (Offset and Scale Factor)?: NO 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Waveform: Name the waveform to be edited. It must al- 
ready exist. 

Sampling Interval: Change the horizontal scale factor. 

Sample Point Number: Index of waveform sample point to change 
amplitude of. 

Horizontal Value: Horizontal value of waveform sample point 
to change. 

Amplitude: Current value at Sample Point Number and 


Horizontal Value. Change to new value to 
be stored into waveform. 


Vertical Scale Factor: Change vertical scale factor. 

Vertical Offset: Change vertical offset. 

Horizontal Offset: Change horizontal offset. 

Normalize Data: (Choice of YES or NO) If yes, waveform 


values are multiplied by the vertical scale fac- 
tor and offset by vertical offset. Vertical 
scale factor becomes 1 and vertical offset be- 
comes 0. 
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EDIT Form (Page 2) ; 


Edit Waveform Characteristics Specification 
aveform Title: 
Horizontal Units: 
Amplitude Units: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Waveform Title: Add, change, or delete a title. 


Horizontal and Amplitude Add, change, or delete units. 
Units: 


NOTE 


No changes are made to the waveform until the F2 (Run) key is 
entered. Delete a text field by pressing the <ctrl> and <Back- ® 
space > keys. 
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EXP Form 


Exp Specification 


nput Waveform: 
Base: 2.71828 


Output Waveform: 
Output Waveform Title: 


Commands: (Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the name of an existing waveform. 

Base: A number. The Output Waveform becomes 
{Base} to the power specified by the Input 
Waveform. 

Output Waveform: Enter the name of the waveform that will 


contain the output values. If it doesn’t al- 
ready exist, it will be created. You can use 
the same name as for input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the w_exp function in Section 8. 
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FFT Form 


FFT Specification 


nput Real Wavetorn: 

Input Imaginary Waveform: 
Output Real Waveforn: 
Output Imaginary Waveform: 


Output Waveform Titles: 


Commands: [Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6-Fud up dn /Field] 


Input Real Waveform: Enter the name of the waveform containing 
the real part of the waveform data. It must 
already exist. 


Input Imaginary Waveform: Enter the name of the waveform containing 
the imaginary part of the waveform data. 
Leave this field blank if there is no imagi- 


nary data. 

Output Real Waveform: Enter the name of the waveform that will & 
contain the real portion of the output data. 
If it doesn’t already exist, it will be created. 


Output Imaginary Waveform: Enter the name of the waveform that will 
contain the imaginary portion of the output 
data. If it doesn’t already exist, it will be 
created. 


Output Waveform Titles: Enter a title to be shown with both output 
waveforms. The program will append 


"(real)" to the real output title and (imag) to 
the imaginary output title. 


The fft functions use quite a bit of temporary memory. Taking the 
fft of a large waveform ( > 4096 points) will fail because not 
enough memory ts available. What you can do is wnte out the 
waveform to disk and quit SPDMENU. White and run a simple 
program to read in the waveform, take the fft, and wnte out the 
two output waveforms to disk. The waveforms may then be read 
into SPDMENU to continue processing. FFT’s of waveforms 
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larger than 8192 points long cannot be handled by SPDMENU or 
user programs. 


For more detail, see the fft and rfft functions in Section 8. 
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GAUSS Form 


Random Gaussian Sequence Specification 


Dutput Yaveform: 
Waveform Title: 
Number of Points: 256 
(Vertical) 
(Horizontal) 

Standard Deviation: 1 
Sampling Interval: 1 Mean: 1 
Horizontal Units: Sec Vertical Units: Volts 


Commands: (Fi-Help F2-Run F3-Top F4-Preuv FS-Back F6-Fud up dn /Field] 


Output Waveform: Enter the name of the waveform. If it 
doesn’t already exist in memory it will be 
created. 

Waveform Title: (Optional) The string is displayed at top of 
graph. 

Number of points: Number of data points in the waveform. 

Sampling Interval: Interval between data samples in (Horizon- © 
tal Units). 

Horizontal Units: Units string, e.g. Sec. 

Standard Deviation: Signal amplitude has a value determined 

Mean: from a gaussian distribution with specified 


mean and standard deviation. 


Vertical Units: Units string, e.g. Volts. 


For more detail, see the randg function description in Section 8. 
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Acquire a 11461/11462 waveforn 


Acquired Waveform: 


Waveform source: TRACE 
Waveforn number: 1 


GPIB address: POLL 
Timeout: 3@ SEC 


Normalize Data (Offset and Scale Factor)?: YES 
Commands: [Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6é-Fud up dn /Field] 


Acquired Waveform: Enter the name of the waveform in which 
the acquired data should be stored. If it does 
not exist, it will be created. 


Waveform Source: Select STO for a stored waveform or 
TRACE for one of the eight active 
waveform traces. 


Waveform Number: Select 1 - 8 if the source is TRACE. Select 1 
- 256 for STOred waveforms. 
GPIB Address: Specify the address (0 - 29) on the GPIB bus 


where the digitizer is located, or use the 
default POLL setting which causes 
SPDMENU to search for the instrument. 


Timeout: Select a value that specifies how long the 
program should wait for a response from the 
GPIB without aborting the acquisition and 
returning a timeout error. Valid values are 


NONE, 3 SEC, 10 SEC, 30 SEC, 100 SEC, 
300 SEC, or 1000 SEC. 


Normalize: If YES is selected (the default), the 
waveform is scaled and the vertical scale fac- 
tor and offset are set to 1.0 and 0.0 respec- 
tively. If NO is chosen, the raw data values 
are stored with the vertical offset and scale 
factor stored separately. 


For more detail, see the get] 1k function description in Section 9. 
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GET2220 Form 


Acquire a 22286 waveform 
Acquired Waveform: | 


Waveform source: CHi 


GPIB address: POLL 
Timeout: 38 SEC 


Commands: [Fi-Help F2-Run F3-Top F4-Preu FS-Back F6-Fud up dn /Field] 


Acquired Waveform: Enter the name of the waveform in which 
the acquired data should be stored. 


Waveform Source: Select the channel or waveform memory of 
the digitizer which should be acquired. The 
selections for this field are CH1, CH2, and 
REF4. 


GPIB Address: Specify the address (0 - 29) on the GPIB bus r 
where the digitizer is located, or use the 
default POLL setting which causes 
SPDMENU to search for the instrument. 


Timeout: Select a value that specifies how long the 
program should wait for a response from the 
GPIB without aborting the acquisition and 
returning a timeout error. Valid values are 


NONE, 3 SEC, 10 SEC, 30 SEC, 100 SEC, 
300 SEC, or 1000 SEC. 


For more detail, see the get2220 function description in Section 9. 
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GET2230 Form 


Acquire a 2238 waveform 


Acquired Waveforn: 
Waveform source: CHi 


GPIB address: POLL 
Timeout: 30 SEC 


Normalize Data (Offset and Scale Factor)?: YES 


Commands: [Fi-Help F2-Run F3-Top F4—-Prev FS-Back F6-Fud up dn /Field] 


Acquired Waveform: Enter the name of the waveform in which 
the acquired data should be stored. 


Waveform Source: Select the channel or waveform memory of 
the digitizer which should be acquired. The 
selections for this field are CH1, CH2, 
REF1, REF2, REF3, or REF4. 


GPIB Address: Specify the address (0 - 29) on the GPIB bus 
where the digitizer is located, or use the 
default POLL setting which causes 
SPDMENU to search for the instrument. 


Timeout: Select a value that specifies how long the 
program should wait for a response from the 
GPIB without aborting the acquisition and 
returning a timeout error. Valid values are 
NONE, 3 SEC, 10 SEC, 30 SEC, 100 SEC, 
300 SEC, or 1000 SEC. 


Normalize: If YES is selected (the default), the 
waveform is scaled and the vertical scale fac- 
tor and offset are set to 1.0 and 0.0 respec- 
tively. If NO is chosen, the raw data values 
are stored with the vertical offset and scale 
factor stored separately. 


For more detail, see the get2230 function description in Section 9. 
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GET2230S Form 


Acquire a 2238 waveforn 


Acquired Waveforn: 


WVaveforn source: CHi 


Port: COMI 
Baud Rate: 2466 


Normalize Data (Offset and Scale Factor)?: YES 


Commands: [Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6-Fud up dn /Field] 


Acquired Waveform: Enter the name of the waveform in which 
the acquired data should be stored. 


Waveform Source: Select the channel or waveform memory of 
the digitizer which should be acquired. The 
selections for this field CH1, CH2, REF1, 
REF2, REF3, or REF4. 


Port: Choose COM1 or COM2. This must cor- 
respond to the port that the 2230 is con- 
nected to. 

Baud Rate: Select 2400 (the default), 1200, or 300. 

Normalize: If YES is selected (the default), the 


waveform is scaled and the vertical scale fac- 
tor and offset are set to 1.0 and 0.0 respec- 
tively. If NO is chosen, the raw data values 


are stored with the vertical offset and scale 
factor stored separately. 


NOTE 
This form can be used with a Tektronix 2220 or 2221 digitizer if: 


1. The source is restricted to CH1, CH2, or REF4. 


2. NORMALIZE is set to NO. 
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GET2430 Form 


Acquire a 2436/2438A/2432/24480 waveform 


Acquired Waveforn: 
Waveform source: CH1 


GPIB address: POLL 
Timeout: 38 SEC 


Normalize Data (Offset and Scale Factor)?: YES 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Acquired Waveform: Enter the name of the waveform in which 
the acquired data should be stored. 


Waveform Source: Select the channel or waveform memory of 
the digitizer which should be acquired. The 
selections for this field CH1, CH2, REF1, 
REF2, REF3, REF4, ADD, MULT, CH1D, 
CH2D, ADDD, or MULTD. 


GPIB Address: Specify the address (0 - 29) on the GPIB bus 
where the digitizer is located, or use the 
default POLL setting which causes 
SPDMENU to search for the instrument. 


Timeout: Select a value that specifies how long the 
program should wait for a response from the 
GPIB without aborting the acquisition and © 
returning a timeout error. Valid values are 
NONE, 3 SEC, 10 SEC, 30 SEC, 100 SEC, 
300 SEC, or 1000 SEC. 


Normalize: If YES is selected (the default), the 
waveform is scaled and the vertical scale fac- 
tor and offset are set to 1.0 and 0.0 respec- 
tively. If NO is chosen, the raw data values 
are stored with the vertical offset and scale 
factor stored separately. 


ig For more detail, see the ger2430 function description in Section 9. 
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GET5223 Form 


Acquire a S223 waveform 


Acquired Waveforn: 


Waveform source: LEFT 


GPIB address: POLL 
Timeout: 386 SEC 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Acquired Waveform: Enter the name of the waveform in which 
the acquired data should be stored. 


Waveform Source: Select the channel or waveform memory of 
the digitizer which should be acquired. The 
selections for this field are LEFT, LEFT1, 
LEFT2, RIGHT, RIGHT1, or RIGHT2. 


GPIB Address: Specify the address (0 - 29) on the GPIB bus 6 
where the digitizer is located, or use the 
default POLL setting which causes 
SPDMENU to search for the instrument. 


Timeout: Select a value that specifies how long the 
program should wait for a response from the 
GPIB without aborting the acquisition and 
returning a timeout error. Valid values are 


NONE, 3 SEC, 10 SEC, 30 SEC, 100 SEC, 
300 SEC, or 1000 SEC. 


Normalize: If YES is selected (the default), the 
waveform is scaled and the vertical scale fac- 
tor and offset are set to 1.0 and 0.0 respec- 
tively. If NO is chosen, the raw data values 
are stored with the vertical offset and scale 
factor stored separately. 


For more detail, see the get5225 function description in Section 9. _ 
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GET7854 Form 


Acquire a 7854 waveform 


Acquired Waveforn. 


GPIB address: POLL 
Timeout: 38 SEC 
Normalize Data (Offset and Scale Factor)?: YES 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Acquired Waveform: Enter the name of the waveform in which 
the acquired data should be stored. 
GPIB Address: Specify the address (0 - 29) on the GPIB bus 


where the digitizer is located, or use the 
default POLL setting which causes 
SPDMENU to search for the instrument. 


Timeout: Select a value that specifies how long the 
program should wait for a response from the 
GPIB without aborting the acquisition and 
returning a timeout error. Valid values are 
NONE, 3 SEC, 10 SEC, 30 SEC, 100 SEC, 
300 SEC, or 1000 SEC. 


Normalize: If YES is selected (the default), the 
waveform is scaled and the vertical scale fac- 
tor and offset are set to 1.0 and 0.0 respec- 
tively. If NO is chosen, the raw data values 
are stored with the vertical offset and scale 
factor stored separately. 


For more detail, see the get7854 function description in Section 9. 
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GET7912 Form 


Acquire a 7912 waveform 


Acquired Waveforn: 
Acquisition Mode: AVERAGE TO CENTER 
Average Count: 1 


GPIB address: POLL 
Timeout: 3@ SEC 


Normalize Data (Offset and Scale Factor)?: YES 
Commands: [Fi-Help F2—-Run F3-Top F4-Prev FS5-Back F6-Fud up dn /“F 


Acquired Waveform: Enter the name of the waveform in which 
the acquired data should be stored. 


Acquisition Mode: Select AVERAGE TO CENTER, SIGNAL 
AVERAGE (see Average Count below), or 
EDGE DETECT. 


Average Count: Choose the number of waveforms that the 
7912 should average for each acquisition. @ 
Preset values are 1, 2, 4, 8, 16, 32, 64. This 
field only has significance if the Acquisition 
Mode is set to SIGNAL AVERAGE. 


Timeout: Select a value that specifies how long the 
program should wait for a response from the 
GPIB without aborting the acquisition and 
returning a timeout error. Valid values are 
NONE, 3 SEC, 10 SEC, 30 SEC, 100 SEC, 
300 SEC, or 1000 SEC. 


Normalize: If YES is selected (the default), the 
waveform is scaled and the vertical scale fac- 
tor and offset are set to 1.0 and 0.0 respec- 
tively. If NO is chosen, the raw data values 
are stored with the vertical offset and scale 
factor stored separately. 


For more detail, see the get7912 function description in Section 9. 
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GET/7D20 Form 


Acquire a 7D28 waveform 


Acquired Waveforn. 


Waveform source: i 


GPIB address: POLL 
Timeout: 38 SEC 


Normalize Data (Offset and Scale Factor)?: YES 


Commands: [Fi-Help F2-Run F3-Top F4—-Preuv FS-Back F6-Fud up dn /Field] 


Acquired Waveform: Enter the name of the waveform in which 
the acquired data should be stored. 


Waveform Source: Select the channel or waveform memory of 
the digitizer which should be acquired. The 
selections for this field are predefined as 1, 
2, 3, 4, 5, or 6. 


GPIB Address: Specify the address (0 - 29) on the GPIB bus 
where the digitizer is located, or use the 
default POLL setting which causes 
SPDMENU to search for the instrument. 


Timeout: Select a value that specifies how long the 
program should wait for a response from the 
GPIB without aborting the acquisition and 
returning a timeout error. Valid values are 
NONE, 3 SEC, 10 SEC, 30 SEC, 100 SEC, 
300 SEC, or 1000 SEC. 


Normalize: If YES is selected (the default), the 
waveform is scaled and the vertical scale fac- 
tor and offset are set to 1.0 and 0.0 respec- 
tively. If NO is chosen, the raw data values 
are stored with the vertical offset and scale 
factor stored separately. 


For more detail, see the get7d20 function description in Section 9. 
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GETRTD Form 


Acquire a RTD716 waveforn 


Acquired Waveforn: 


Waveform source: CHi 
Location: 1 


GPIB address: POLL 
Timeout: 36 SEC | 


Normalize Data (Offset and Scale Factor)?: YES 


Commands: (Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Acquired Waveform: Enter the name of the waveform in which 
the acquired data should be stored. If it does 
not exist, it will be created. 


Waveform Source: Select CH1 or CH2. 

Waveform Number: Select 1 - 32. 

GPIB Address: Specify the address (0 - 29) on the GPIB bus 
where the digitizer is located or use the 


default POLL setting which causes 
SPDMENU to search for the instrument. 


Timeout: Select a value that specifies how long the 
program should wait for a response from the 
GPIB without aborting the acquisition and 
returning a timeout error. Valid values are 
NONE, 3 SEC, 10 SEC, 30 SEC, 100 SEC, 
300 SEC, or 1000 SEC. 


Normalize: If YES is selected (the default), the 
waveform is scaled and the vertical scale fac- 
tor and offset are set to 1.0 and 0.0 respec- 
tively. If NO is chosen, the raw data values 
are stored with the vertical offset and scale 
factor stored separately. 


For more detail, see the gettd function description in Section 9. 
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GRAPH Form 


Graph Waveforn 
(Page 1 of 2) 


Waveform 1. Waveforn 2: 


X-axis: LINEAR X-axis: LINEAR 

Y-axis: LINEAR Y-axis: LINEAR 
Scaling: AUTO Scaling: AUTO 

X-min: X-min: @ 

X—max : X-max: @ 


Y-min: Y-min: @ 
Y—max : Y-max: 8 
Commands: [Fi-Help F2-Run F3-Top F4-Prey FS-Back F6-Fud up dn /Field] 


NOTE 
GRAPH HAS A TWO PAGE FORM. 


WAVEFORM 1, 2: Previously defined waveforms. 

X-AXIS, Y-AXIS: Select LINEAR or LOG. Negative and zero 
data will be omitted from LOG plots. 

SCALING: Select AUTO or MANUAL. 

X/Y-MIN, X/Y-MAX: min and max values to be shown in plot win- 
dow; changing these has no effect unless scal- 
ing is MANUAL. 
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GRAPH Form (page 2) 


Graph Vaveforn 
(Page 2 of 2) 


Grid Style: MNO GRID 
Line Style: SOLID 

Axis Color: WHITE 
Curve Color: RED 

Text Color: YELLOW 
Background Color: BLUE 


Commands: [Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6-Fud up dn /Field] 


DESTINATION: Select SCREEN, WHOLESCREEN, PLOT- 
TER or PRINTER. WHOLESCREEN is 
the destination to use to generate full screen 
graphs. If you choose PRINTER or PLOT- 
TER, be sure that a printer or plotter driver 
has been installled at boot time using the 
device= statements in CONFIG.SYS. See 


Section 2 for details. 
GRID STYLE: Select NO GRID, DOTTED, or SOLID. 6 
LINE STYLE: Select SOLID, LONG DASH, DOTTED, 


DASH DOTTED, MED DASH, DASH 
2DOTS, SHORT DASH, MARKERS, IN- 
TERP, ANTI-ALIASED, or INTERP/- 
ANTI-ALIASED. The interpolation 
process sometimes generates peak data that 
is outside the amplitude range of the the 
waveform data. This collides with the auto- 
scaling mechanism and results in missing 
data on the graph. Use manual scaling when 
this happens. Only some display devices 
have sufficient color depth to permit anti- 
aliased display the IBM 8514 is one. If the 
device doesn’t have sufficient color depth, 
SOLID is substituted for ANTI-ALIASED. 


AXIS COLOR: Select RED, WHITE, BLACK, GREEN, 


CURVE COLOR: BLUE, YELLOW, CYAN, or MAGENTA. ®@ 
TEXT COLOR: 
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Inverse FFT Specification 


nput Keai Waveform: 

Input Imaginary Waveform: 
Output Real Vaveform: 
Output Imaginary Vaveform: 


Output Waveform Titles: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Real Waveform: Enter the name of the waveform containing 
the real part of the waveform data. It must 
already exist. 


Input Imaginary Waveform: Enter the name of the waveform containing 
the imaginary part of the waveform data. It 
must already exist. 


Output Real Waveform: Enter the name of the waveform that will 
contain the real portion of the output data. 
If it doesn’t already exist, it will be created. 


Output Imaginary Waveform: Enter the name of the waveform that will 
contain the imaginary portion of the output 
data. If it doesn’t already exist, it will be 
created. Enter nothing if no imaginary data 
is desired (a real inverse FFT), or delete the 
waveform name if one already exists. 
(NOTE: <ctrl> <Backspace> will delete a 
string.) 


Output Waveform Titles: Enter a title to be shown with both output 
waveforms. For a complex inverse FFT, 
"(real)" will be appended to the real output 
title and "(imag)" to the imaginary output 
title. 
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The ifft uses quite a bit of temporary memory. Taking the ifft of a 
large waveform may fail because not enough memory ts available. @ 
What you can do is write out the waveform to disk and quit 

SPDMENU. Write and run a simple program to read in the 

waveform, take the ifft, and wnte out the output waveform(s) to 

disk. The waveforms may then be read into SPDMENU to con- 

tinue processing. 


For more detail, see the ifft and ifft functions in Section 8. 
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INT Form 


Integration Specification 


End-of—-fArray: REPEAT 


Output Waveform: 
Output Waveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the name of the waveform to be in- 
tegrated. It must already exist. 

End-of-Array: How to substitute for data beyond the ends 
of the array. 

Output Waveform: Enter the name of the waveform that will 


contain the integrated data. If it doesn’t al- 
ready exist, it will be created. You can use 
the same name as for input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the integrate function in Section 8. 
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INTERP Form 


Interpolation Specification 


End-of-fArray: REPEAT 

Type of Interpolation: SINC 
Interpolation Factor: 4 
Filter Length: 17 

User Filter VWaveforn: 


Output Vavefornm: 
Output Waveform Title: 
Commands: (Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /“Field] 


Input Waveform: Enter the name of the waveform to be inter- 
polated. It must already exist. 

End-of-Array: How to substitute for data beyond the ends 
of the array. 

Type of Interpolation: Select LINEAR, SINC, or USER_FILT 

Interpolation Factor: Ratio of number of new points to add; must 
be an integer greater than 1. An “expan- 


sion" factor. 


Filter Length: Length of interpolation filter. It should be 
an odd number that is at least 3, if Type is 
SINC or USER_FILT. It is ignored if Type 
is LINEAR. 


User Filter Waveform: (Only needed if Type is USER_FILT.) The 
coefficients of a user-defined Finite Impulse 
Response interpolation filter. This filter is 
assumed to have even symmetry and odd 
length. At least ("Filter Length" + 1)/2 
coefficients should be supplied. 


Output Waveform: Enter the name of the waveform that will 
contain the interpolated data. If it doesn’t 
already exist, it will be created. You can not 
use the same name as for input. 


Output Waveform Title: Enter a title (optional). i, 


For more detail, see the w_interp function in Section 8. 


4-48 Signal Processing & Display 


SPDMENU Reference 


LOG Form 


Log Specification 


nput Vaveform: 


Log Base: 2.71828 


Output Vaveform: 
Output Waveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the name of an existing waveform. 


Log Base: A number. The Output Waveform becomes 
log to the base {Log Base} entered of the 
Input Waveform. 


Output Waveform: Enter the name of the waveform that will 
contain the logs. If it doesn’t already exist, it 
will be created. You can use the same name 
as for input. 


Output Waveform Title: Enter a title (optional). 


NOTE 


The absolute value of negative numbers are used. Log(0) is O! 


For more detail, see the w_/og function in Section 8. 
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MAX Form 


Max Specification 
Input Uaveform: 


<Input Waveform or double const>: 


Output Waveform: 
Output Waveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the name of an existing waveform. 
<Input Waveform or double An existing waveform name or a number. 
const >: Both waveform input names can be the same. 
Output Waveform: Enter the name of the waveform that will 


contain the maximum of the first and second 
waveforms or the first waveform and the con- 


stant. If it doesn’t already exist, it will be ®@ 


created. You can use the same name as for 
input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the w_max and wc_max functions in Section 8. 
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MIN Form 


Min Specification 


a 
<Input Waveform or double const>: 


Output Waveform: 
Output Waveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the name of an existing waveform. 
<Input Waveform or double An existing waveform name or a number. 
const>: Both waveform input names can be the same. 
Output Waveform: Enter the name of the waveform that will 


contain the minimum of the first and second 
waveforms or of the first waveform and the 
constant. If it doesn’t already exist, it will be 
created. You can use the same name as for 
input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the w min and we min functions in Section 8. 
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MPULSE Form 


Pulse Measurement Specification 


nput Waveform: 


Waveforn Zone 
Left: 6 Elements Crossed: 1 
Right: 255 End-of -Array: REPEAT 
Proximal: 8.1 
Search Direction: RIGHT Mesial: 8.5 
Histogram Mode: MODE Distal: 8.9 


Commands: (Fi-Help F2-Run F3-Top F4-Prey FS-Back F6-Fwd up dn “Field! 


Input Waveform: Enter waveform name, it must already exist. 
Left: The leftmost point to consider (in Horizon- 
tal Units). 
Right: The rightmost point to consider (in Horizon- 
tal Units). 
Search Direction: RIGHT or LEFT. © 
Histogram Mode: Whether to use the peaks or the means in 


the bimodal histogram to determine the high 
or low levels. 


Elements Crossed: The number of data elements that must stay 
crossed for a crossing to be valid. 

End_of_ Array: Determines how data at the ends of the 
array are handled. 

Proximal: The "10% level" (hence default is .1). 

Mesial: The "50% level" (hence default is .5). 

Distal: The "90% level" (hence default is .9). 


The data measured by mpulse is attached to the input waveform (as a note 
string) and is displayed whenever the waveform is graphed. It also accompanies 
the waveform when it’s written to a file. This string replaces any notes string 


that was previously attached. The fields are: 
p amp: Pulse amplitude (Vertical Units) _ 
riset: Risetime (Horizontal Units) 
r pro: Rising proximal location (Horizontal Units) 
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r mes: Rising mesial location (Horizontal Units) 
r dis: Rising distal location (Horizontal Units) 
fallt: Falltime (Horizontal Units) 

} f pro: Falling proximal location (Horizontal Units) 
f mes: Falling mesial location (Horizontal Units) 
f dis: Falling distal location (Horizontal Units) 
p wid: Pulse width (Horizontal Units) 
dutyf: Duty factor (fraction of period the pulse is 

above pamp/2) 
perio: Period (Horizontal Units) 
NOTE 


mpulse works with pulse trains and with single pulses. Duty Fac- 
tor and Penod are printed if three pulse transitions are found be- 
tween Left and Right (a pulse train). Pulse Width is printed when 
only two pulse transitions are found (a single pulse). 


For more detail, see the p/s_meas function in Section 8. 
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MSTAT Form 


Vaveform Statistics Specification 
Tnput Uaveform: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter waveform name, it must already exist. 


The data measured by mpulse is attached to the input waveform (as a note 
string) and is displayed whenever the waveform is graphed. It also accompanies 
the waveform when it’s written to a file. This string replaces any notes string 
that was previously attached. 


The fields are: 
min: The minimum amplitude found. (Vertical © 
Units) 
min I: The leftmost location at which min was 


found. (Horizontal Units) 


max: The maximum amplitude found. (Vertical 
Units) 

max 1: The leftmost location at which max was 
found. (Horizontal Units) 

mean: The mean amplitude. (Vertical Units) 

s dev: Standard deviation in amplitude. (Vertical 
Units) 

rms: Root mean square of the amplitude. (Verti- 
cal Units) 

var: The variance of the amplitude. (Vertical 
Units) 8 


For more detail, see the meanstd and minmax functions in Section 8. 
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MULT Form 


Mult Specification 


D 
<Input Waveform or double const>: 


Output Waveform: 
Output Waveform Title: 


Commands: ([Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the name of an existing waveform. 


<Input Waveform or double An existing waveform name or a number. 
const >: Both input names can be the same. 


Units: Multiplier units (this field only appears 
when the field above contains a number. 


Output Waveform: Enter the name of the waveform that will 
contain the product (first*second). If it 
doesn’t already exist, it will be created. You 
can use the same name as for input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the w_imult and wc_mult functions in Section 8. 
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POLAR Form 


Polar Specification 


nput Real Waveforn: 
Input Imaginary Waveform: 


Unwrap Phase: FALSE 
Phase Units: DEGREES 
‘| Delay Adjustment: @ 


Output Magnitude Waveform: 
Output Phase Waveforn: 


Output Waveform Title: 


Commands: (Fi-Help F2-Run F3-Top F4-Prev F5-Back F6-Fud up dn /Field] 


Input Real Waveform: 
Input Imaginary Waveform: 


Unwrap Phase: 


Phase Units: 


Delay Adjustment: 


Enter the names of the waveforms to be con- 
verted. 


They must already exist. 


Select whether or not the phase data will be 
"unwrapped" or confined to the range -180 
degrees to +180 degrees. 


Select DEGREES, RADIANS, or GRADS. ® 


The delay value causes a linearly varying 
phase component whose slope is 2*pi*delay 
to be subtracted from the phase after conver- 
sion to polar coordinates. 


Output Magnitude Waveform:Enter the names of the waveforms that will 


Output Phase Waveform: 


Output Waveform Title: 


contain the output data. If they don’t al- 
ready exist, they will be created. You may 
use the same names as for input. You may 
omit one (but not both) of the names. That 
output waveform will not be generated. 


Enter a title (optional). Same title applies 
to both outputs but "(mag)" or "(phase)" will 
be appropriately appended. 


For more detail, see the polar function in Section 8. 
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POWER Form 


Power Specification 


nput Vaveform: 
Exponent: 2 


Output Vaveforn: 
Output Waveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the name of an existing waveform. 

Exponent: A number. The Output Waveform becomes 
the Input Waveform raised to the power 
{Exponent}. 

Output Waveform: Enter the name of the waveform that will 
contain the output values. If it doesn’t al- 
ready exist, it will be created. You can use 
the same name as for input. | 

Output Waveform Title: Enter a title (optional). 

Output Waveform Title: Enter a title (optional). The same title ap- 


plies to both outputs. 


For more detail, see the power function in Section 8. 
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PROCESS Form 


Run User Process on Vaveform 


Program Name: process 
. Waveform Name: File Name: W1.WAV 


. Waveform Name: File Name: W2.WAU 
. Waveform Name: File Name: W3.WAYV 
. Waveform Name: File Name: W4.WAVU 


Commands: (Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6-Fud up dn “Field] 


Program Name: The name of the user program, including 
path. If the program takes command line 
switches, they may be entered here. 


Waveform Name(1-4): Enter waveform names that your program 
creates or reads. The first waveform name 
is required. The other three are optional. 


File Name(1-4): Use the default W1.WAV - W4.WAV or - 
override with your own file names. If a cor- 
responding waveform is filled in, it will be 
written to this file (if the waveform exists) 
before calling your program, and read back 
into the corresponding waveform after your 
program has terminated. Include path infor- 
mation if the file is not in the current direc- 


tory. 
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RANDB Form 


Random Binary Sequence Specification 


Output VUaveform: 
Waveform Title: 
Number of Points: 256 
(Vertical) 
(Horizontal ) 
Amplitude: i 
Sampling Interval: 1 Baseline Offset: @ 
Horizontal Units: Sec Amplitude Units: Volts 
Probability: 6.5 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Output Waveform: Enter the name of the waveform. If it 
doesn’t already exist in memory it will be 
created. 

Waveform Title: (Optional) The string will be displayed at 
top of the graph. | 

Number of points: Number of points in the waveform. 

Sampling Interval: Interval between data samples in Horizontal 
Units. 

Horizontal Units: Units string, e.g. Sec. 

Amplitude: Peak-to-Peak Signal amplitude. 

Baseline Offset: "DC" value (corresponds to binary 0 level). 

Amplitude Units: Units string, e.g. Volts. 

Probability: Probability that binary level is 1 (0. < = prob 
<= 1.0). 


For more detail, see the randb function description in Section 8. 


Signal Processing & Display 4-59 


SPDMENU Reference 


READ Form 


Read Waveform Specification 


nput Waveform File Nane: 
Output Waveform: 
Normalize Data (Offset and Scale Factor)?: NO 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform File Name: Enter file name that contains waveform data 
in SPD ADIF format. Include path informa- 
tion if the file is not in the current directory. 
Also, see the Settings Form for how to set 
the default waveform directory. 


Output waveform: The waveform name will be created 


automatically when you specify the Input 
Waveform File Name but you can change it. 


If it doesn’t already exist, a memory struc- 
ture will be created for it. 


Normalize: Select YES or NO. Indicate whether the of- 
fset and scale factor for Y values should be 
applied to the graph or stored separately. 


For more detail, see the afile_to_wf and file to_wf function descriptions in Sec- 
tion 8. 
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RECT Form 


Rectangular Specification 


mpu agnitude Waveform: 


Input Phase Waveform: 


Phase Units: DEGREES Output Real Waveforn: 
Delay Adjustment: @ Output Imaginary Vaveforn: 


Output Vaveforn Title: 


Commands: [Fi-Help FZ2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Magnitude Waveform: Enter the names of the waveforms to be con- 


verted. 
Input Phase Waveform: They must exist. 
Phase Units: Select DEGREES, RADIANS, or GRADS. 


The program attempts to set this value ac- 
cording to what is in the Input Phase 
Waveform units field. You will be warned if 
you override and the program thinks you’re 
wrong! 


Delay Adjustment: The delay value causes a linearly varying 
phase component whose slope is 2*pi*delay 
to be added to the phase before conversion 
to rectangular coordinates. 


Output Real Waveform: Enter the names of the waveforms that will 
Output Imaginary Waveform: contain the output data. If new, they will be , 
created. You may use the same names as 
for input. You may omit one (but not both) 
of the names. The output that you omit will 
not be generated. 


Waveform Title: String will be displayed at top of graph. (Op- 
tional) 


For more detail, see the rectang function description in Section 8. 
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SETTINGS Form 


Settings Specification 
Waveform Precision: N OF 
Waveforn File Directory: . 
Waveform File Extension: .WAV 


Automatic Graphs: ON 


Help File Search Path: .\HELP;C:\TEKNSPD\MENUNHELP;A:\HELP;B: >A: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Waveform Precision: Select whether new waveforms will carry 
single precision or double precision data. 
Single precision (the default) saves memory 
space at the expense of accuracy but almost 
all applications can use single precision suc- 
cessfully. 


Waveform File Directory: Name the default directory for reading and 
writing waveform files. The default may be ©} 
overridden by explicitly naming the directory 
in any io form. 


Waveform File Extension: The default waveform file name extension. 


Automatic Graphs: If ON, waveforms will be displayed when- 
ever the data in them is altered. If OFF, 
they won’t. The appearance of the 
automatic graphs is set in the "graph" form. 


Help File Search Path: Specifies directories to search for help files. 
Separate directory names with a ’;’ charac- 
ter. Use drive designations where necessary. 
For example: 
"\HELP;C:\TEK\SPD\MENU\HELP" 
searches the HELP directory under the cur- 
rent directory, and then the HELP directory 
on drive C: in the standard SPDMENU in- 


stallation directory. & 
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SIN2 Form 


Sine-squared Pulse Specification 
Output Vaveform: 
Waveform Title: (Horizontal ) 
Number of Points: 256 


Sampling Interval: 1 
(Vertical) Horizontal Units: Sec 
Width: 128 
Amplitude: 1 
Baseline Offset: @ Peak Offset: 8 
Amplitude Units: Volts 


Commands: [Fi-Help F2-Run F3-Top F4-Preu FS-Back F6-Fud up dn /Field] 


Output Waveform: Enter the name of the waveform. If it 
doesn’t already exist in memory it will be 
created. 

Waveform Title: String will be displayed at top of graph. (Op- 
tional) 

Number of points: Number of data points in the waveform. 

Sampling Interval: Interval between data samples in Horizontal 
Units. 

Horizontal Units: Units string, e.g. Sec. 

Width: Width of pulse at half its amplitude 
(Horizontal Units). 

Peak Offset: Offset of the peak from the center of the 
waveform in Horizontal Units. 

Amplitude: Difference between baseline offset and peak 
amplitude. 

Baseline Offset: Baseline (reference) amplitude. 

Amplitude Units: Units string, e.g. Volts. 


For more detail, see the sin2 function description in Section 8. 
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SINC Form 


Since (Sin (x)/x) Specification 
Dutput Uaveform: 
Waveform Title: (Horizontal ) 
Number of Points: 256 

Sampling Interval: 1 

(Vertical) Horizontal Units: Sec 
Period: 25.6 

Amplitude: 1 
Baseline Offset: @ Peak Offset: @ 
Amplitude Units: Volts 


Commands: [(Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Output Waveform: Enter the name of the waveform. If it 
doesn’t already exist in memory, it will be 
created. 

Waveform Title: String will be displayed at top of graph. (Op- 
tional) 

Number of points: Number of points in the waveform. 

Sampling Interval: Interval between data samples in Horizontal 
Units. 

Horizontal Units: Units string, e.g. Sec. 

Period: Width of main lobe; e.g., 2e-2 horizontal 
units. 

Peak Offset: Offset of the peak from the center of the 
waveform in horizontal units. 

Amplitude: Signal amplitude at center of pulse. 

Baseline Offset: Baseline (reference) amplitude. 

Amplitude Units: Units string, e.g. Volts. 


For more detail, see the sinc function description in Section 8. 
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SINEMEAS Form 


Identify sine wave components 


Window Type: HAMMING 
Threshold: 8 

Phase Units: DEGREES 
Secondary Component: 2 


Commands: [Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6-Fud up dn /Field) 


Input Waveform: Enter the name of the waveform to be 
analyzed. It must already exist. 
Window Type: Select HAMMING, RECTANGULAR, 


TRIANGULAR, HANNING, BLACK- 
MAN, or FLATTOP 


Threshold: The minimum amplitude that qualifies a 
@ sinewave component to be included in the 
analysis. If Threshold is 1, a warning mes- 
sage is displayed and the minimum threshold 
for the Window Type selected is used in- 


stead. 
Phase Units: Select DEGREES, RADIANS, or GRADS. 
Secondary Component: The sinemeas function returns up to 10 sine 


wave components, although only two can be 
displayed. This field specifies which com- 
ponent (2 - 10) is to be displayed with the 


first component. 


For more detail, see the sinemeas function in Section 8. 
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SINEWAVE Form 


Output Waveform: 
Waveforn Title: (Horizontal ) 
Number of Points: 256 
Sampling Interval: 1 
(Vertical) Horizontal Units: Sec 
Frequency: @.804 
Amplitude: 6.5 
Baseline Offset: 8 Phase: @ 
Amplitude Units: Volts Phase Units: DEGREES 


Commands: [Fi-Help F2-Run F3-Top F4-Prey FS-Back F6-Fud up dn “Fieldl] 


Output Waveform: Enter the name of the waveform. If it 
doesn’t already exist in memory it will be 
created. 

Waveform Title: String will be displayed at top of graph. (Op- 
tional) 

Number of points: Number of points in the waveform. 

Sampling Interval: Interval between data samples in Horizontal _ 
Units. 

Horizontal Units: Units string; e.g., Sec. 

Frequency: Number indicating the frequency in Hertz. 
(Negative frequency results in 180 degree 
phase shift). 

Phase: Initial phase angle. 

Phase Units: Select DEGREES, RADIANS, or GRADS. 

Amplitude: Signal amplitude. 

Baseline Offset: Amplitude at sine(0); i.e., "DC" value. 

Amplitude Units: Units string; e.g., Volts. 


For more detail, see the sinewave function description in Section 8. 
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SQUARE Form (Page 1) 


Squarewave Specification 
(Page 1 of 2) 
0 s (Hor izontal ) 
Waveforn Title: 
Number of Points: 256 Sampling Interval: 1 
Horizontal Units: Sec 
Period: 128 


Delay: 32 


Duty Factor: 8.5 
Commands: [(Fi-Help F2—-Run F3-Top F4-Prev F5-Back F6-Fud up dn /Field] 


NOTE 
This is a two page form. 
Output Waveform: Enter the name of the waveform. If it 


doesn’t already exist in memory it will be 
created. 


Waveform Title: String will be displayed at top of graph. (Op- 
tional) 


Number of points: Number of data points in the waveform. 


Sampling Interval: Interval between data samples in Horizontal 
Units. 


Horizontal Units: Units string; e.g., Sec. 


Period: Length of one waveform cycle; e.g., 2e-2 
horizontal units. 


Delay: Offset from beginning to Amplitude/2 point 
on first transition (expressed in horizontal 
units) 


Duty Factor: Ratio of pulse duration to the period length, 
where the pulse duration is the amount of 
time at amp Amplitude/2 


6 For more detail, see the square_wave function description in Section 8. 
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SQUARE Form (Page 2) 


Squareuwave Specification 
(Page 2 of 2) 
Baseline Offset: -@.5 (Vertical) 
Amplitude Units: Volts 


(Rising Transition) (Falling Transition) 


Edge Type: RAMP Edge Type: RAMP 
Rise-time: 16 Fall-time: 16 


Commands: [Fi-Help F2-Run F3-Top F4-Preuv FS-Back F6-Fud up dn /“Field] 


Amplitude: Signal amplitude 
Baseline Offset: Initial amplitude value 
Amplitude Units: Units string; e.g., Volts 
Edge Type: Select RAMP (linear edge) or SIN“%2 (sine- 
squared edge) 
Rise /Fall Time: Distance (in Horizontal Units) between 10% © 


and 90% of Amplitude in transition 


For more detail, see the square _wave function description in Section 8. 
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SQRT Form 


Square Root Specification 


Output Waveform: 
Output Waveform Title: 


Commands: [(Fi-Help F2-Run F3-Top F4-Preuv FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the name of an existing waveform. 


Output Waveform: Enter the name of the waveform that will 
contain the output values. If it doesn’t al- 
ready exist, it will be created. The Output 
Waveform becomes the square root of the 
Input waveform. You can use the same 
name as for input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the w_sqrt function in Section 8. 


Signal Processing & Display 4-69 


SPDMENU Reference 


SUB Form 


Sub Specification 


nput Waveform: 
<Input Waveform or double const>: 


Output Waveform: 
Output Waveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the name of an existing waveform. 


<Input Waveform or double An existing waveform name or a number. 
const >: Both input names can be the same. 


Output Waveform: Enter the name of the waveform that will 
contain the difference (first - second). If it 
doesn’t already exist, it will be created. You 
can use the same name as for input. ® 


Output Waveform Title: Enter a title (optional). 


For more detail, see the w_sub and wc_sub functions in Section 8. 


4-70 Signal Processing & Display 


SPDMENU Reference 


TAPER Form 


Taper Specification 


Window Type: HAMMING 
Window Fraction: 1 


Output Waveform: 
Output Waveform Title: 


Commands: [Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6-Fud up dn /Field] 


Input Waveform: Enter the name of the waveform to be dif- 
ferentiated. It must already exist. 
Window Type: Select HAMMING, RECTANGULAR, 


TRIANGULAR, HANNING, BLACK- 
MAN, or FLATTOP 


Window Fraction: The fraction of the input waveform over 
6 which the window Is to be applied. 1.0 
means the entire waveform. .8 means the 
middle 20% will be unaltered. 


Output Waveform: Enter the name of the waveform that will 
contain the windowed data. If it doesn’t al- 
ready exist, it will be created. You can use 
the same name as for input. 


Output Waveform Title: Enter a title (optional). 


For more detail, see the taper function in Section 8. 
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UNIF Form 


Random Uniform Sequence Specification 
Output Yavefornm: 
Waveform Title: 
Number of Points: 256 
(Vertical) 
(Horizontal ) 
Minimum Value: 6 
Sampling Interval: 1 Maximum Value: 1 
Horizontal Units: Sec Vertical Units: Volts 


Commands: (Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fwd up dn /Field] 


Output Waveform: Enter the name of the waveform. If it 
doesn’t already exist in memory, it will be 
created. 

Waveform Title: String to be displayed at the top of a graph. 
(Optional) 

Number of points: Number of points in the waveform. 

Sampling Interval: Interval between data samples in Horizontal ® 
Units. 

Horizontal Units: Units string; e.g., Sec. 

Minimum Value: Minimum amplitude. 

Maximum Value: Maximum amplitude. 

Vertical Units: Units string; e.g., Volts. 


For more detail, see the randu function description in Section 8. 
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UREAD Form 


Read User File Specification 


nput Waveform File Nane: 
Data Format: ASCII 
Number Precision: SINGLE FLOAT 
First Value to Read: 1 
Read Every: 1 


Output Waveform: 


Commands: [Fi-Help F2-Run F3-Top F4-Prev FS-Back F6-Fud up dn /Field] 


Input Waveform File Name: Enter file name that contains waveform data 
in format to be described by entries below. 
Include path information if the file is not in 
the default directory (see the Settings Form). 


Data Format: Select ASCII, BINARY, or IBM BASIC BI- 
NARY 
eS} Number Precision: Select SINGLE FLOAT, DOUBLE 
FLOAT, 16BIT INT, or 32BIT INT. 


First Value to Read: Count, or index, of first waveform value. 
Use this to skip header data. 1 means first 
value in file is a waveform value. 


Read Every: 1 if every value is a waveform value, 2 if 
every other, 3 if every third... 


Output waveform: The waveform name will be created 
| automatically when you specify Input 
Waveform File Name, but you can change it. 
If it doesn’t already exist, it will be created. 


For more detail, see the df_to_wf function description in Section 8. 
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WRITE Form 


Write ASCII Waveform Specification 


nput Waveform or "*’: 


Output Waveform File Name: 
Mode: ASCII 


Commands: [(Fi-Help F2-Run F3-Top F4-Preyv FS-Back F6-Fud up dn /“Field] 


Input Waveform: Enter waveform name; it must already exist. 
Enter ’*’ to select all waveforms. 


Output Waveform File Name: Enter file name. Include path information if 
the file is not going to the current directory. 
Also, see the Settings Form for how to set 
the default waveform directory. The File 
Name will be created automatically once 
Input Waveform is entered, but you can @ 
change the name. If all waveforms were 
selected, the automatic names are used and 
there is no opportunity to change them. 


Mode: Select ASCII or BINARY. The mode refers 
to how numbers are stored in the standard 
ADIF file. 


For more detail, see the wf_to_afile and wf_to_file function descriptions in Sec- 
tion 8. 
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Where SPDMENU Looks for Support Files 


In order to find the overlays it needs, SPDMENU.BAT and SM.EXE must be in 
your current working directory, or in your PATH environment variable. 


@ SPDMENU.M 


The first action performed by SPDMENU is to read in the menu file that 
defines the structure of the menus. It looks for a file named SPDMENU.M in 
the following directories: 


@ Current directory 
@ c:\TEK\SPD\MENU 
® b:\MENU 
@ a:\MENU 
If that search fails, SPDMENU displays an error message and quits. If you have 


placed the file somewhere else, you’ll need to start SPDMENU with the direc- 
tory that contains the SPDMENU.M file named on the command line; i.e..,: 


c>SPDMENU Directory-Name 


SPDMENU Help Files 
© NOTE 


While some of the help information is contained within 
SPDMENU, detailed help text is retrieved from data files when it 
is requested. By default, the program looks for the files in the fol- 
lowing directones: 

@ HELP (within the current directory) 

@ c:\TEK\SPD\MENU\HELP 

@ a:\HELP 

@ b: 

@ a: 


If you have placed the files somewhere else, you need to tell SPD MENU where 
to find them. This can be done by using the settings operation in the control sub- 
menu. That operation allows you to alter the search path for the help files. 
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Using SPD Without a Hard Disk 


To use SPDMENU on a system that does not have a hard disk, begin by modify- 
ing the CONFIG.SYS and AUTOEXEC.BAT files on your boot diskette as ex- 
plained in Section 2, Getting Started. You also need to copy the appropriate 
device drivers from disks 1, 2, and 3 to the boot diskette. To nn SPDMENU 
after re-booting your system with the modified boot disk, insert the copy of disk 
6 in drive a: and a copy of disk 7 (help files and the menu definition file) in drive 
b:. Then type SM b:. (The SPDMENU.BAT file works only with the hard disk.) 
Be sure to keep the copy of disk 6 in drive a: so that the overlays can be found. 
You can use drive b: for your waveform files after replacing the copy of disk 7 
with a scratch disk, but remember to put the disk 7 copy back in drive b: if you 
want to access the help files. 


The help files can still be used, but the work disk in drive b: must be replaced 
with the help file disk (disk 7) before pressing F1. Be sure to insert the work disk 
in drive b: before attempting to save a waveform to disk. 


Unused Functions 


The following functions are not accessed from SPDMENU: 


dim_reorder pils_amp pls_pkfind 
eq fir pls_dutyf pls_pospk 
make_subwf pls_edge pt_interp 
make target pis_negpk 


These functions can be accessed from your own programs and from custom code 
you write to be used with the process form. In particular, pls pospk() can be 
used to calculate positive overshoot and pis_negpk() calculates negative over- 
shoot. See the Section 8 of this manual for more details on these functions. 


Waveform Units Processing and Scaling in SPDMENU 


Units are strings used to describe the dimensions of a waveform. They can be 
represented by any arbitrary string and are delimited by a space character. A 
units string might look like this: 


Volts Volts Sec / Watts meter dbm0 


In general, the horizontal units and horizontal scale factor of combined 
waveforms must be the same. If they are different, one waveform’s horizontal 
units and horizontal scale factor are used. The horizontal units are then marked 
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with the "units conflict" character (a trailing question mark) as shown in the fol- 
lowing example: 


"Volts Sec / Watt ?" 


The horizontal scaling factor (hsf), also called the data sampling interval, is the 
"time" increment between adjacent samples, though the units might indicate 
something other than time. The default value is 1. 


When computing vertical units, the concept of units combination follows the 
rules of algebra, resulting in a rationalized fraction. 


The following sections provide examples of how units are affected when combin- 
ing the units and horizontal scale factor of two waveforms or one waveform and 
a constant. The waveforms are usually referred to as "a" and "b". 


NOTE 


The vertical scale factors are assumed to both be 1.0, while the ver- 
tical offsets are both assumed to be 0.0. Therefore, waveforms that 
are combined should first be normalized when acquired. It is also 
assumed that the horizontal offsets of both waveforms are the 
same. 


Addition /Subtraction 


When performing real (or complex) addition or subtraction on two (or four) 
waveforms, the units of "a" should be identical to those of "b". If they are identi- 
cal, the resulting units will be the same. 


If the units are not identical, the units of the first waveform are used and are fol- 
lowed with a "?", as shown in the following example: 


Volts? 


When adding or subtracting a waveform and a constant, the units will be the 
same as those of the waveform. 


Multiplication 


When multiplying two waveforms, numerators from each of the units are con- 
catenated. If there are any denominators, the concatenated numerator is fol- 
lowed by a"/", and the concatenated denominators follow as shown: 


If units of "a" = "Volts Sec/Amp" and units of "b" = “Sec/Volt":, the resultant 
(before cancellation) is: 


Volts Sec Sec / Volts Amp 


or after cancellation: 


Sec Sec / Amp 
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Complex multiplication follows the same rules, except that the real and imagi- 
nary partners of a complex waveform must agree as to the vertical units, horizon- 
tal units, and hsf. 


Division 

When dividing waveforms, the vertical units are combined as in multiplication, 
but the dividing waveform’s numerator will appear in the result’s denominator, 
and vice versa. 


Log/Exp 
When finding the log or exponent of a waveform, the vertical units are cleared, 
since log() and exp() produce unit-less values. 


Sqr, Power 


In the case of sqr and power(waveform, n) where n = k + i/j, i = 1, 2, 3, ..., ap- 
propriate groupings of identical units are made. Those needed are retained and 
groups are replicated if necessary. For example: 


sqr(Volts Volts) = Volts, and 
power(Volts Volts Volts, 333) = Volts. 
Similarly, power(V AVA VA /WWW, 667) = VAVAV/WW. 


Rectangular to Polar 


When converting waveforms from rectangular to polar coordinates, there are 
two input waveforms ("a" and "b") that are in rectangular coordinates, and two 
Output waveforms ("c" and "d") that are the polar representations of the input. 
The units for "c" (the magnitude waveform) are the same as either input 
waveform when the input waveforms have identical units. 


When the input waveforms do not have identical units, the units for "c" are the 


units of "a" with the question mark appended as shown in the following example: 


Volts ? 


The units for "d" (the phase waveform) are forced to be "Deg", "Grad", or" “ 
(no units), depending on the phase units specified (DEGREES, GRADS, or 
RADIANS). 


Polar to Rectangular 


When performing a polar to rectangular conversion, there are two input 
waveforms, "a" (magnitude) and "b" (phase), in polar coordinates, and two out- 
put waveforms, "c" and "d", the rectangular representations of the input. Units 
for “c" and "d" are copies of the units of "a". 
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The displayed phase units are picked off the "b" waveform. You can override 
this selection, but you will get a warning message when the function runs. The 
function is performed assuming the selected units are valid. 


The horizontal units and hsf are computed in the same fashion as for addi- 
tion/subtraction/multiplication/division. 


fft/rfft Time to Frequency 


When performing a time-to-frequency conversion, the input waveform(s) must 
have the same vertical units, horizontal units, and hsf. If they are not the same, 
the first waveform’s units or hsf are used to compute the output waveform’s at- 
tributes, and the units are marked as questionable. 


The output waveform’s vertical units are computed by the rules of multiplication 
using the first input waveform’s vertical and horizontal units. 


The output waveform’s horizontal units are the inverse of the input waveform(s) 
horizontal units. If present, Sec in the inverted units denominator is replaced 
with Hz in the numerator. 


The output waveform’s hsf is changed to 1.0/(N * hsf), where N is the length of 
the input array(s). 


After an fft function is called, the resulting waveforms are multiplied by the 


6 input waveform’s original hsf. 


ifft/irfft Frequency to Time 

When performing a frequency-to-time conversion, the transformations are iden- 
tical to fft/rfft, except that Hz in the resulting inverted units denominator are 
replaced with Sec in the numerator, and N is the length of the output array(s). 


Differentiate 


When differentiating a waveform, the output waveform’s vertical units are com- 
puted by dividing the input waveform’s vertical units by the input waveform’s 
horizontal units. 


The output waveform’s horizontal units and hsf are the same as the input 
waveform’s. The output waveform is also divided by the hsf of the input 
waveform. 


Integrate 

When integrating a waveform, the output waveform’s vertical units are com- 
puted by the rules of multiplication, using the input waveform’s vertical units 
multiplied by the input waveform’s horizontal units. 


The output waveform’s horizontal units and hsf are the same as the input 
waveforms. The output waveform is also multiplied by the hsf of the input 
waveform. 
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Interpolation 


When performing interpolation, the output waveform’s vertical units and 
horizontal units are the same as the input waveform’s. The hsf is divided by the 


interpolation factor, n. @ 
Decimation 
When performing decimation on a waveform, the output waveform’s vertical 


and horizontal units are the same as the input waveform’s. The hsf is multiplied 
by the decimation factor, n. 


Convolution 


When convolving two waveforms, the transformations are identical to those for 
multiplication. 


Correlation 


When correlating two waveforms, the transformations are identical to those of 
multiplication. 


Sinemeas 


When the sinemeas() function is applied to a waveform, each frequency 

returned in the Freq[] array must be divided by (wave length * horizontal scale) 

to get the correct frequencies in the phase units selected by the phase units © 
parameter. 


Summary 


Table 4-1 summarizes units and scale factor adjustments. 
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SUMMARY OF UNITS un ee FACTOR ADJUSTMENTS 
“Operation(s) = WH? hs? Output 
Units Units Multiplier 

add, sub V H hsf 1 
min, max 
log, exp _? H hsf 1 
sqrt note I H hsf 1 
pwr note 1 H hsf 1 
decimate V H hsf*factor 1 
interpolate V H hsf/factor 1 
(cpx) mult ¥iI"V2Z H hsf 1 
conv, corr 
(cpx) div V1/V2 H hsf 1 
differentiate V/H H hsf 1/hsf 
integrate V*H H hsf hsf 
fft, rfft V*H note 2 1/(N;*hsf) hsf 
ifft, irfft ¥"*H note 3 1/(No*hsf) hsf 
polar to rectang Vv H hsf 1 
rectang to polar 

magnitude Vv H hsf 1 

phase "Deg", H hsf 1 

"Grad" or" " 
Where: 

V= input vertical units V’ = output vertical units 

H = input horizontal units H’ = output horizontal units 

hsf = input hsf hsf" = output hsf 

Nj = Input real wave length No = output real wave length 

NOTE 1 


An attempt is made to group the units according to the order of 
power (for sqr, the order is 1/2). If this attempt fails, the units are 
set to "?" (the "questionable units” string). 
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NOTE 2 


An attempt is made to substitute "Hz" for "Sec" in the numerator. 
If this substitution fails, the horizontal units are set to 1/H, the in- 
verse of the input’s honzontal units. 


a) e 


An attempt is made to substitute "Sec" for "Hz" in the numerator. 
If this fails, the vertical units are set to 1/H, the inverse of the 
input’s honzontal units. 
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Section 5 
SPD C 
Programming 


This section explains how to access the SPD functions from a C program. It as- 
sumces that you already know how to write C programs. Its purpose is to help 
you use the SPD functions to produce meaningful programs. In general, no at- 
tempt is made to give a detailed discussion of the parameter lists of the SPD 
functions. See the Sections 8 through 10 for these details. 


C Header Files 


The SPD C interface includes a set of header files that define the data 
strucrures, types, and constants equivalent needed for SPD C programming. 
These files are found in the \tek\spd\include directory. They can be identified 
by the .A suffix. Constants such as colors (WHITE, BLUE, etc.) that are needed 
for the graphics functions are provided. So are constants for signal processing 
functions such as window types for tapering (HAMMING, BLACKMAN, etc.). 
See Appendix C for a complete listing of these files. 


Besides providing helpful constant definitions, the header files also contain func- 
tional prototypes of all the SPD functions. Functional prototypes define the 
kinds of parameters that are required by the SPD functions. When functional 
‘prototypes are used, Microsoft C can detect parameter mismatches in the com- 
pile step rather than at run time. This greatly speeds up debugging of SPD C 
programs. 
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Programs that call SPD signal processing functions must include the SPD 
header files because they define key data types such as WAVEFORM. In order 
to use the header files simply put the line 


#include "tekspd.h" 


at the start of your program. 


C Waveform Access Macros 


Besides offering a complete set of signal processing functions, the SPD C inter- 
face also provides a set of macros that permit you to access the fields of a 
waveform data structure such as offsets, scaling factors, and units strings without 
suffering the overhead of a function call. These macros are defined in the 
header file wav.h which is automatically included in your program if you manual- 
ly include tekspd.h as described above. These macros are listed in Appendix C. 


The Structure of an SPD Program 


SPD applications usually contain the following sections: 


Generating or Acquiring waveform data 
Processing the waveform (FFT, convolution, etc.) 
Defining curves 

Controlling the appearance of the graph 


Displaying curves 


Storing waveforms on disk 


In your actual code, these sections may be clearly defined, interspersed, or em- 
bedded in loops or other program structures. For illustration purposes, they are 
treated as clearly separated sections. 


Generating or Acquiring Waveform Data 


Waveform data in your application program can come from one or more of 
three possible sources: data acquired from an instrument into a data array, data 
read from a file, and/or waveforms generated by a SPD or user defined function. 
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Acquired Data 


The acqm5.lib acquisition library supplies functions that can be called from your 
programs to acquire waveforms from the same digitizers supported by 
SPDMENU. In fact, the parameters of the functions in acqm5.lib correspond 
exactly to the menu fields of the corresponding SPDMENU forms and provide 
the same functionality. With these functions, you do not need to allocate data 
arrays, request preamble data, or manipulate the data to get a fully normalized 
SPD waveform structure. All of the GPIB knowledge needed to acquire and 
scale waveforms for the supported Tektronix digitizers has been built into the ac- 
quisition functions. The following code fragment shows how to acquire a 
waveform from channel one of a Tektronix 2430 digitizer: 


#include "tekspd.h" 
WAVEFORM £*wave = NIL; /* pointer to waveform */ 


/* Acquire a waveform from CH1 of the 2430 

m/f 

if (get2430(wave,W DOUBLE,CH1,POLL,30S,TRUE)!=NOERROR) { 
fprintf(stderr, “Waveform acquisition failed."); 
return; 


/* process wave here */ 


If the digitizer you are using is not supported by acqmS.lib, you can use a 
Tektronix-supplied package such as the GPIB "C" interface library or a package 
that you supply to acquire data from an instrument into a data array. This invol- 
ves acquiring curve data as well as scale factors and offsets which you can apply 
to the acquired array. When the data has been placed into an array, you can use 
the arrl_to_wf() function to create an SPD waveform structure containing the 
data. 


The following code illustrates this process: 


#include "tekspd.h" 
main() 


WAVEFORM *wave = NIL; /* pointer to waveform */ 
/* 
* Allocate the working data area. Space is allocated for 
* a 100 element double array. 
al 
arrlen = 16; 
if ((sigarr=(double*)mk_array((long)arrlen, 

(long )sizeof(double) ) )==NIL) { 
fprintf(stderr, “Insufficient memory for array."); 
return; 

} 
/* 


* Perform the necessary operations to load the array with 


~ 
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* data. The code that is inserted here depends on the 
* type of application (data acquisition, data generation, 
* etc.) For illustration purposes the array is filled 
* with a ramp. 
"/ 
for (i = 0; i < arrlen; i++) 
Sigarr(i) = i; 
/* 
* Convert the array to a waveform 
wf 


if (arrl_to_wf(sigarr, arrlen, W_DOUBLE, &wave)!=NOERROR) { 
fprintf(stderr, "Array to waveform failed."); 
return; 


NOTE 


The arr_to_wf() and arrl1_to wf() functions, as well as all of the 
acquisition functions in acqm5.lib, allocate new memory for the 
waveform, so if the waveform pointer passed to these functions al- 
ready points to waveform data, the pointer is re-assigned to point 
to the new waveform. This causes the old data to be lost and 
reduces the memory available to your program. 


If your program repeatedly uses one of these functions with the 
same waveform pointer, be sure to free up the old memory with 


free_wf() before re-using the pointer. = 


Reading Waveforms from Disk Files 


If you have previously stored a waveform on disk using the SPD wf_to file() or 
wf_to_afile() function, you can read it back in using file_to_wfQ) or afile_to_wf(). 
Two routines are provided to be compatible with earlier versions of SPD which 
used proprietary and distinct formats for binary (file_to_wf) and ASCII 
(afile_to_wf) waveforms. In the current version, these functions are simply two 
entry points to the same routine. They can read the following formats automati- 
cally by detecting the file format and using the appropriate instructions to read 
it: 


@ ADIF (Analog Data Interchange Format) ASCII 
@ ADIF binary 


ADIF is a new general purpose file format for expressing analog data. The 
details of this format are in Appendix E. 
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NOTE 


Like the array-to-waveform functions, these functions allocate new 
memory for the waveform that is read from disk so if the 
waveform pointer passed to these functions points to existing data, 
the old data ts lost and the memory available to your program is 
reduced, so be sure to free up the old memory with free_wf() 
before re-using a waveform pointer. 


The following program fragment reads a file named my.wav into a waveform 
structure named wave: 


#include "tekspd.h" 


main( ) 
WAVEFORM *wave ; /* pointer to waveform struct */ 
/* 
* Read the data file into a working waveform array 
"f 
if (afile_to_wf("my.wav", &wave) != NOERROR) { 
free wf(wave); /* free waveform storage area */ 
return; 
} 
/* 


Continue processing the data. 


*/ " 

} 
To read data that is in a non-standard format, the df_to_wf() function lets you 
read the raw data from most disk files. Note that this function can only read 
point values; it does not know how to read scale factors, offsets, units strings, 
etc. You specify the type of data in the file (ASCII, binary, or BASIC binary), 
how many initial values to skip to bypass header information that the function 
does not know how to process, and how many data values to skip between array 


values. After reading the file, use other SPD calls and macros to scale, label and 
title your waveform. 


Generating Waveforms with SPD Functions 


The SPD library also provides a number of functions which can generate sine 
wave, square wave, sine®, and sine(x)/x waveforms. In addition, uniform, binary, 
and gaussian random waveforms can be created. Detailed information about 
these functions is available in the Function Libraries part of this manual. 
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NOTE 


These functions do not allocate space for the waveform. You must 
do this yourself using a function such as create1_wf(). 


The following program shows how waveform generation is accomplished. It is 
included on the distribution disks as simple.c. The example will: 


@ create a one dimension, one tuple waveform 
@ fill the waveform with sine squared data (using sin2() ) 


@ display the resulting waveform (see later sections for discussion) 


#include "tekspd.h" 
#define DIMLENGTH 256 /* length of the dimension */ 
main() 


{ 


WAVEFORM *wave; /* waveform pointer */ 
double ampl, width, pkpoint, base; /* explained below */ 


/*® 

* Create a waveform data structure with space allocated 

* for a single tuple, single dimension of type double. 

afd 

if (createl_wf(DIMLENGTH, W_DOUBLE, &wave) != NOERROR) 
return(1); 


/* 
* Generate a sine2 pulse with the following parameters 
a 
width = 40.0; /* Half amplitude width = 40 samples */ 
pkpoint = 0.0; /* Center the pulse in the waveform */ 
ampl = 10.0; /* Peak amplitude (above dc level)*/ 
base = 0.0; /* baseline offset */ 
if (sin2(ampl, width, pkpoint, base, wave) != NOERROR) { 
free wf(wave) ; 


return(1); 
} 
/* 
* Display the waveform data 
*/ 
Br_init(); /* Initialize graphics software */ 
gr_dev("DISPLAY"); /* Select the CRT display device */ 
gr_defw(1, wave); /* Associate waveform with data set 1 */ 


/* Associate the range 0O through */ 
/* DIMLENGTH-1 with data set 0 */ 
gr_defa(0, 0.0, (double)DIMLENGTH-1); 


/* Generate curve "1" using data set 0 */ 
/* for the y axis and data set 1 for */ 
/* = axis. */ 

gr_curv(1, 0, 1, WHITE, SOLID); 


gr_dsply(); /* Actually display the graph */ 
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gr_pause(); /* Give the user a chance to see it */ 


gr_close(); /* Close the graphics device */ 


Processing the Waveforms 


Once you have one or more waveforms in memory, you can perform many types 
of processing on them. Some of functions available are Fast Fourier Transforms 
(forward and inverse), waveform arithmetic (including complex arithmetic), min- 
imum and maximum, integration and differentiation, interpolation and decima- 
tion, etc. Many waveform manipulation functions are also available. A complete 
list of functions is found in Section 7. Function details are given in Sections 8 
through 10. 


The SPD Signal processing routines do not take care of scaling their own output 
or adding the appropriate units to output waveforms. You will have to use SPD 
functions to handle the output waveform according to the table at the end of 
Section 4, which shows the scaling and units processing requirements of each 
function. Detailed scaling and units processing examples are also included in 
the individual function descriptions in Section 8. 


As an example, if you have acquired or read in a waveform named wave, the fol- 
lowing code fragment converts it to the frequency domain and then to polar 
notation: 


WAVEFORM *wave; 
WAVEFORM *real, *imag; 
WAVEFORM *mag, *phase; 
long size; 
double vscale, new_hsf; 


size = (int)wave_size(wave) ; 


/* CONVERT wave TO THE FREQUENCY DOMAIN */ 
createl wf( (size/2)+1, W_FLOAT, &real); 
createl_wf( (size/2)+1, W_FLOAT, &imag); 


vscale = dim _scale(wave,0); 
new _hsf = 1.0/(vscale * size); 


taper(wave,FLATTOP,1.0,wave) ; 
rfft(wavel, real, imag); 


/* scale the results of rfft */ 
dim_scale(real,0) = new_hsf; 
dim_scale(imag,0) = new_hsf; 
we_mult(real,vscale) ; 
we_mult(imag,vscale); 


/* CONVERT real AND imag TO THE POLAR */ 
createl wf( (size/2)+1, W_FLOAT, &mag); 
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createl wf( (size/2)+1, W_FLOAT, &phase) ; 
polar(mag, phase, DEGREE, TRUE,0.0,mag, phase) ; 


/* scale the results of polar */ 
dim_scale(mag,0) = new_hsf; 
dim_scale(phase,0) = new_hsf; 


Notice the allocation of space for the resulting waveforms. In general, all 
waveforms must be created, usually using create_wf() or createl_wf(), before 
they can be the output of an SPD function. The exceptions to this rule are: 


The output of the acquisition functions (e.g. get2430() ) automatically 
create the output waveform. 


The arr_to wf() and arrl_to_wf() functions create their own output 
waveform from the array provided as an input parameter. 


The file_to wf(), afile_to_wf(), and df_to_wf() functions create waveforms 
based on the data they find in the disk file presented to them. 


The reason for not automatically creating output waveforms is that you may 
want to re-use an existing waveform. Also, many of the functions can’t predict 
what the size (or data type) of the output waveform should be. 


Waveform Measurement 


SPD’s extensive waveform measurement capabilities such as statistical and pulse 
measurements are listed in Section 7 and detailed in Section 8. For example, 
given a waveform, wave, containing a pulse, the following program measures and 
prints on the screen the amplitude, rise and fall times, overshoot, and under- 
shoot. 


Calls are made to pls_edge() and pls_amp() to determine the top and bottom 
levels of the pulse. The reference point for the bottom of the pulse is defined as 
20 samples before the leading edge of the pulse. Once the top and bottom 
levels are known, the rise-time and fall-time are measured using pls_rtime() and 
pls_ftime(). The pulse overshoot is measured by calling pls_pospk() to deter- 
mine the peak value of the pulse. The percent overshoot is determined by relat- 
ing this value to the previously measured top and bottom values. 


#include "tekspd.h" 


main() 
WAVEFORM “*wave; /* pointer to pulse waveform */ 
long Lt, mh; /* left & right search bounds */ 
long lead,trail;/* approx pulse edge locations*/ 


double top, bot; /* pulse top and bottom values */ 
double pkloc, pkval; /* pulse peak information */ 
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} 


double farr[4); /* fall-time parameter storage */ 
double rarr(4]; /* rise-time parameter storage */ 
/* 
* Obtain ‘wave’ here by acquisition, generation, file 
* read, etc. 


wf 
/* 
* Measure the parameters of the pulse waveform with 
* pls_amp(), pls_edge(), pls_rtime(), pls_ftime() and 
* pls_pospk(). Input parameters to these routines are: 
ve 
* li = 20 Start in from the end to avoid 
* ri = 80 running past the end of the waveform 
* dir = RIGHT Searching is done from left to right 
* nav = 5 Average 5 samples to determine level 
*n = 3 number of elements that must remain 
* above transition for it to be valid 
* eoaa = EA_REPEAT set to default, shouldn't be needed 
* tlevel = NIL use default tlevel values (10,50,90) 
¥/ 
Li = 20; 
ri = 80; 


pls_ edge(sqw, li, ri,RIGHT,3,EA_ REPEAT,&lead,&trail,NIL); 
pls_amp(sqw, lead, trail, Lead- 20,5, EA_REPEAT,&top, &bot); 
pls_rtime(sqw,li,ri,RIGHT,top, bot, 3, EA, REPEAT ,NIL,rarr); 
pls_ftime(sqw,li,ri,RIGHT,top,bot,3,EA __ REPEAT, HIL., Z6LE ) ; 
pls_pospk(sqw, lead, trail,&pkloc, &pkval) ; 


/* 

* Print the results of the measurement 

*/ 
printf ("PARAMETER\t\tMEASURED VALUE\n") ; 
PELE (Sewn 2 (rea ees \n"); 
printf("Pulse Amplitude --\t2z8.2f\n", top-bot); 
printf("Rise-time --\t%8.2f\n", rarr[0])); 
printf("Fall-time <<\ine.erw, farr[0)): 
printf("Overshoot mend, ee ee 

(pkval-top)/(top-bot)*100. ); 

printf("Peak Location -~-\t%8.2f\n", pkloc); 


This results in the following output: 


PARAMETER MEASURED VALUE 
Pulse Amplitude 10.00 
Rise-time ee 
Fall-time 2.94 
Overshoot 3.34% 
Peak Location Jo. OU 


Space Requirements 


Please be aware that some functions require a lot of intermediate storage and 
will fail if that storage is not available. You can estimate the amount of memory 
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taken by a waveform by multiplying the number of points in the waveform by 
four bytes for single precision data, and eight bytes for double precision data. 
Space requirements for the various functions are detailed in The SPD Reference 
Manual. 


As an example, to correlate two 4k point waveforms (single precision) using 
fcorr() requires the following memory (the two temporary arrays are always 
double precision): 


inputs: 2waveforms * 4096 points * 4 bytes/point = 32,768 bytes 
temp: 2waveforms * 8192 points * 8 bytes/point = 131,072 bytes 
output: 1lwaveform * 4096 points * 4 bytes/point = 16,384 bytes 
TOTAL 180,224 bytes 


Sub-waveforms 


If you are working with multi-dimension or multi-tuple waveforms, remember 
that most SPD functions work only on the first dimension or tuple. To access 
other dimensions use the dim_reorder() function. The tup_reorder() function 
allows you to resequence the tuples in a waveform so that the one you want is 
first. 


These functions, with zone_dim(), can be used to create a sub-section of a 
waveform. 


5-10 Signal Processing & Display 


SPD C Programmin 


The following program illustrates a procedure for examining a part of the 
waveform array using the SPD functions. In this example, a section of a two 
dimensional 4 x 10 waveform is examined. The area to be isolated is row 2, 
columns 2 through 7. This is shown pictorially as: 


Column 


Fig. 5-. Array created with create_wf(). 


Column 


UL bt BAL J SBiiijiiaass LUE URERRE:  TORRER TERRE teu ReeDy SEG TERRE SEE Ae 
mona ai mb eg a ai a pT 


Fig. 5-2. Shaded area indicates elements pointed to by 
subwave after first call to zone_dim(). 


Column 
4 5 


0 | 8 9 
VTS ETRE | ALR NA TAB OL HLH ERNE LEL BACARRA PU a 
ae: nite fiiinniat eee a 
Fig. 5-3. Shaded arca indicatcs clements pointcd to by 
subwave after second call to zone_dim(). Subwave created 


by first call to zone_dim() has been deleted (by using 
DELETE* option). 


The SPD functions dim_reorder() and zone_dim() are used to isolate the subsec- 

tion of the waveform. This is accomplished by first making a subordinate 

waveform, "subwave", that consists of data from row two. This is accomplished 

in the first call to zone_dim(). The next step is to reduce the number of columns 

to include only columns two through seven. This is accomplished in the second 

call to zone_dim(). Finally, the two dimensional waveform is converted to one 
é dimension by dim_reorder(). The program is: 


#include "tekspd.h" 
main() 


WAVEFORM *wave; 
WAVEFORM *subwave; 
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int typarr(1)]; 

int order[1]; 
long dimarr([2]; 
/* 

* Create the two dimensional 4 x 10 waveform 
* 4 rows -- dimension 0 

* 10 columns -- dimension 1 

«/ 


typarr[0] = W_DOUBLE; 

dimarr[0] = 4; 

dimarr[({1] = 10; 

create wf(2, dimarr, 1, typarr, &wave); 


/* 

* load the waveform with data 

ad 

/* 

* Subsection the waveform array. 

a 

zone_dim(wave,0,(long) 2,(long) 2,KEEP, &subwave) ; 
zone_dim(subwave,1,(long) 2,(long) 7,DELETE, &subwave) ; 
order(0) = 1; 

dim_reorder(subwave, 1, order, DELETE, &subwave) ; 


/ bd 

* Perform operations on the subsection of the waveform 

* by using subwave. 

al 

} 

Note that only the original wave and final subwave data structures remain. The 
intermediate subwave structures are deleted using the DELETE keyword in the 
calls to zone_dim() and dim_reorder(). 


SPD Graphics 


To display a waveform using the SPD graphics functions, you must perform the 
following steps, each of which is discussed in subsequent sections: 

initialize the graphics system 

define the curves 


customize the appearance of the graph (optional) 


display the graph 
Initialize the Graphics System 


Before performing any other graphics calls (functions starting with gr_) you 
must call gr_init() which initializes the variables in the graphics subsystem to 
their default values. This function has no parameters. 
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Define the Curves 
Two steps are required to produce a curve from your data. 


First, data sets for the X values and for the Y values must be defined using one 
of the following functions: 


gr_defa() (automatic generation of a set, given the starting and ending 
points) 


gr_defd() (from an array of doubles). 
gr_deff() (from an array of float values) 
gr_defw() (from the first dimension and tuple of a waveform) 


Typically, the X data set is defined using gr_defa(), which defines a data set 
based on the end points. The end points are double precision floating point 
numbers, so by using the first and last scaled X values as endpoints, the data set 
is scaled automatically. It is also possible to define the X data set from a 
waveform or a numeric array. This might be done if you have acquired data in 
XY mode from a digitizer. 


The X axis definition from simple.c is: 
gr_defa(0, 0.0, (double)DIMLENGTH-1) 


The Y values are usually generated from a waveform with gr_defw(), since 
waveform structures are required by the signal processing functions, but you can 
also use gr_deff() or gr _defd() to create data sets directly from numeric arrays. 


The Y axis data set definition from simple.c is: 
gr_defw(1, wave); 


Second, a curve is defined as one data set on the X (independent) axis versus 
another set on the Y (dependent) axis. Any number of curves can be defined 
and will be displayed together on the same axes later when gr_dsply() is called. 
The function gr_curve() allows selection of line color and style (dejagged, inter- 
polated, solid, or one of several dot /dashed patterns). A similar function, 
gr_mrkr() generates a curve displayed as markers, rather than lines. 


The curve definition from simple.c is: 


gr_curv(1,0,1, WHITE, INTRP); 
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where WHITE and INTRP are pre-defined constants from the header files 
tekgr.h specifying the curve color and line style. INTRP specifies an interpolated 
line style. 


The graphing library automatically scans the data for minimum and maximum 
values and generates the axis ticks and labels using these values, unless the 
graph limits have been explicitly set using gr_xrang() or gr_yrang(). Data ex- 
ceeding the specified graph limits is not displayed. (Automatic scaling is based 
on the input data values. The interpolated display generation adds data values 
that may be outside the range of the input data; the result may be a clipped dis- 
play. (Use manual scaling, gr_xrang() or gr_yrang(), in this case.) 


Curves can be added to an existing display by using gr_addcv() and gr_addmk(), 
as long as the viewport is not changed. Data sets and curves can be redefined 
whenever needed, although redefining datasets does not automatically redefine 
the curve that uses them; you must call gr_curve() or gr_mrkr() again. You 
can also undefine data sets and curves by using gr_undef() and gr_uncrv(). 


Using gr_type(TEXTONLY) generates a graphic display consisting only of text if 
text only is specified. In this mode, text notes defined by gr text are the only 
graphic output. Gr_type(DISPLAYGRAPH) resets the system to display 
graphics again. 


Customize the Appearance of the Graph (Optional) 


Functions are provided to include a title, subtitle, x and y axis labels, and a 
legend; separate colors can be specified for each. The major (labeled) and 
minor (unlabeled) tick mark spacings can be specified for each axis. 


The background color of your display can be modified by calls to gr_back(). The 
three integer parameters specify the mix of red, green, and blue in the back- 
ground color. The actual color that appears on the screen depends on which 
CGI device driver is being used to display graphics on the screen. Please note 
that the effect of gr_back() is on the entire display, not simply on the current 
viewport. It takes effect when you invoke gr_dsply(). 


By default, the entire graphic display area is used to display a graph. However 
the function gr_vwpt() allows specification of a viewport within the display, al- 
lowing multiple graphs per display. The viewport area can be outlined using 
gr_frame(). A box can be drawn around the graph area alone with gr_box(). 


Displaying the Graph 


SPD graphics display occurs between calls to gr_dev(), which opens the device 
specified by the parameter, and gr_close() which closes the device. If the device 


5-14 Signal Processing & Display 


SPD C Programming 


specified in gr_dev() is "DISPLAY", the screen is switched from text mode to 
graphics mode. Similarly, gr_close() returns the screen to text mode. As a side 
effect, both calls clear the screen. The currently defined graph is output by the 
function gr_dsply(). The viewport area is first cleared and then the graph and 
associated text are drawn. Since only the viewport is cleared, careful use of curve 

@ definition followed by gr_vwpt() and gr_dsply() allows multiple graphs to be dis- 
played at once. 


The function gr_update() uses the current data and curve definitions to redraw 
only that part of the graph containing the curves. The current data and curve 
definitions can be different from those used when the entire graph was drawn 
using gr_dsply(); the window range remains the same. If any newly defined data 
is outside the window, it is clipped. The window is not recalculated, since this 
would require redrawing the axes, tick marks, and labels. Specifying a new 
graphics device does not affect the currently defined graph. Thus, a graph can 
be sent to a plotter by the following function calls: 


gr_init(); /* Initialize the graphics system */ 
/* 


* curve definition and graph customization 
* calls go here 


a J 

gr_dev("PLOTTER") ; /* open the plotter (could be 
* PRINTER or DISPLAY too */ 

gr_dsply(); /* output the graph */ 

gr_close() /* close the display device */ 
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Figure 5-4 shows the graphic output of simple.c. 


Fig. 5-4. Simple.c graph. 


NOTES 


1. Your CONFIG.SYS file must contain statements loading the ¢$ 
proper graphics device drivers for the display, printer, or plotter that 
you wish to use. See Section 2, Getting Started, for details. 


2. When gr _dev() is executed with an argument of "DISPLAY", 
your screen goes into graphics mode. From that point until 

gr _close() is called, text written to the screen appears in unusual 
colors and with possible side effects. This approach is not recom- 
mended. 


Storing Waveforms on Disk 


Besides displaying the graphs, you may also want to save your waveforms on 

disk. The functions wf_to file() and wf_to_ afile() store waveforms on disk. 

Wf_to_afile() stores the waveform as an ADIF ASCII file; that is, the numeric 

values are stored as ASCII strings and are human readable. Wf_to_file() uses 

the ADIF binary format in which numeric values are stored in binary form.  ) 


For example, the following command writes the ramp waveform created above 
to an ASCIT ADIF file named "ramp.wav". 
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wf to_afile(wave,"ramp.wav"); 


The resulting file looks like this: 


ADIF ( STD ( VERSION 0.99 ) | 


IDENTIFY ( 
SOURCE (PACKAGE "SPD V2.2") | 
DATE "1988-10-06" | 


| TIME "13:09:27" 
) 
DIM=X1 ( 
TYPE IMPLICIT | 
SCALE 1 | 
OFFSET 0 | 
SIZE 16 
) | 
DIM=Y2 ( 
TYPE EXPLICIT | 
SCALE 1 | 
OFFSET 0 | 
ENCODE (HIRANGE 3.40282e+038) 


) | 

TRACE=SPD1 ( 
INDEPENDENT (DIM (LABEL X1) ) | 
DEPENDENT (DIM (LABEL Y2) ) 

) 

DATA ( CURVE ( VALUES 


- = bd = bd = = J = 


OOnNrnDN Uf WNFH OC 


= 


Compiling and Linking a C Program 


You can compile and link a Microsoft C program named foo.c by entering: 


cScomp foo (compiles) 


@ c5link foo (links) 


where cScomp.bat is: 
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cL <¢ “Al -Oil -Zpl Z71.¢ >21.msg 
and c5link.bat is: 


link %1+\spd\lib\fpem5, 21, ,acqm5+grm5+spdm5 
+llibce /STACK:7000 /F /PAC /NOE /NOD 


You can also perform both steps at once by entering 
eS foo 


C5.bat combines the contents of cScomp.bat and cSlink.bat. 


The default stack size set by the Microsoft C compiler may not be sufficient for 
SPD programs, particularly if they involve graphic display of data sets with a 
large number of points or anti-aliased or interpolated displays. A stack size of 
at least 7000 bytes is recommended when using the SPD graphics library. 
C5link.bat automatically sets the stack size to 7000 during linking. If a different 
stack size is required, modify the /STACK switch to a larger value. 


A common symptom of insufficient stack size is a graphics display that doesn’t 
quite happen. The border and the labels appear but the waveform display 
doesn’t. Increasing the stack space usually takes care of the problem (unless 
something else is wrong). The SPD libraries were compiled using the default 
capability for detecting and reporting stack overflow. It is recommended that 
you do likewise in order to prevent the grievous results that can occur without 
this mechanism. 


NOTE 


C5link.bat does not explicitly mention the C library path because 
it is established in the AUTOEXEC.BAT file by defining the LIB 
environment vaniable. For example, if the Microsoft libraries are 
in a directory named \msc5\lib\, then the line: 


set lLib=c:\msc5\lib;c:\tek\spd\lib 


should be added to your AUTOEXEC.BAT file.to make the 
default libraries available to the Linker. 


Compiler Compatibility 


The SPD libraries (spdm5.lib, the signal processing library, acqm5.lib the ac- 
quisition library, and grm5.lib, the graphics library) are "large" model libraries 
compiled and linked with Microsoft C version 5.0. Large model means that both 
text and data space can exceed 64k. 
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SPD Function Return Values 


Nearly all SPD functions return a value of type "ERRORTYPE" which notifies 
the calling program of the success or relative failure of the function call. If an 
error occurs in the call, messages that describe the error are sent to the stderr 
output. The messages identify the called SPD routine that was responsible even 
though the actual error may have been discovered by a function that is deep 
within the SPD libraries. It’s wise for the user application to check the return 
value from a call to a SPD function. WARNING messages generally advise that 
some action was taken that may or may not be expected but the results of the 
operation may be suspect. FATAL errors indicate that the operation failed for 
some reason and the results, if any, are invalid. CRASH errors are serious; con- 
tinued execution of the program could cause deleterious effects. 


Error Messages 


During graphics operations, between calls to gr_dev() and gr _close(), error mes- 
sages may not reach the screen or, if they do, are not recognizable (in fact, they 
may mangle graphic output). You should redirect error messages to a file 
during graphic display portions of your program using the err_file() function 
and then look at that file afterwards. 


Error messages, both those in the SPD libraries, and those that your program 
generates with the rpt_err() function, precede the message text with a calling list 
of functions that help you locate just where the error occurred. To make use of 
this feature, use the set_err() function to add the current C routine name to the 
call list that rpt_err() prints. This should be done to all of your routines that con- 
tain SPD calls or that call other functions that call SPD routines. The clr_err() 
function removes the name that was last placed on the call list by set_err(). To 
make sure that the call list does not become jumbled, make sure that every C 
routine that contains a set_err() call also calls clr_err() at every possible exit 
from that routine. 


Floating Point Errors 


The SPD signal processing library will intercept floating point errors that occur 
in math library routines such as log() and provide reasonable substitute results. 
If you run the enable_fpe() function, these interceptions are counted and 
reported along with other standard errors until you invoke the disabl_fpe() func- 
tion. 
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Using The Error Functions 


The following example illustrates the use of the SPD Error Functions in a C 
program. 


#include "tekspd.h" - 


main () /* Your application program */ 

{ 
char *logname; /* name of error logging file */ 
ERRORTY PE err; /* your error variable */ 
ERRORTYPE funcl(); /* declare your function */ 
enabl_fpe(ON); /* Enable floating point 


exception capture/reporting */ 


logname = "“report.err"; 

if ((errfile = fopen(logname, "w")) == NULL) { 
fprintf(stderr, "Can't open error file\n"); 
exit(i); 


err = funcl(...); /* Call a your function 1 */ 


dsabl _ fpe(); /* Disable floating point 
exception capture/reporting */ 


} 
ERRORTYPE funcl(...) /* user function 1 */ - 


{ 
ERRORTYPE err; /* funcl error variable */ 


set_err("funcl"); /* Save the name of the function */ 


err = rpt_err(WARN,"some user error occurs here"); 


[A floating point exception occurs, the interrupt handler calls inc_fpe, ex- 
ecution proceeds from the point of the interrupt] 


/* At this point err is set to whatever 
error has occurred during execution. 
The user error and floating point 
exception are reported by clr_err and the 
value returned is the worst case error of 
err and WARN */ 
return(clr_err(err)); 


5-20 Signal Processing & Display 


SPD C Programming 


General Limits 


The following general limits govern the use of SPD with C programs: 


@ Up to 32 data sets can be defined (numbered 0-31). The amount of 
data stored is limited by the amount of available memory. 


@ Up to 32 curves can be defined at one time (numbered 0-31) 


@ Titles, labels, and text strings can have a maximum of 128 characters 
each. 


® A maximum of 48 text notes can be defined at one time. 


@ The largest single-precision floating point waveform that you can suc- 
cessfully process with rfft() or correlate with itself is 8192 points. This 
limitation is due to the large amount of temporary storage needed for 
these functions. If you have a large number of waveforms in memory, 
have memory resident software (besides your SPD program), or use 
double precision data, the maximum size you can process may be less 
than 8192 points. 


Example C Programs 


The following complete example C program incorporates most of the informa- 
tion discussed above. It creates two waveform data structures, fills the first with 
a sine(x)/x function, integrates the first waveform putting the results in the 
second, and displays both waveforms on one set of axes. A variation discussed 
later on displays both waveforms in separate viewports. 


This program is provided in source form as EXAMPLE1.C on disk 4. The varia- 
tion is stored as EXAMPLE2.C. Each section is discussed, in turn. 


The first line of the program is an #include statement that brings in the SPD in- 
clude files. (See the listing in Appendix C.) This should be included at the begin- 
ning of any C program that uses the SPD functions. Then the floating point 
exception handler is enabled by a call to enabl_fpe(). The last piece of initializa- 
tion is to call the gr _init() function which initializes the SPD graphics data struc- 
tures and status variables. This function should be called before any other SPD 
graphics calls are made. 


#include tekspd.h 

WAVEFORM *wave, *wave2; 

double ampl, freq, pkpoint, dc,; 
double hsf; 

double startpt, endpt; 

short setno, xsetno, ysetno, curvno; 
short rr, gg, bb; 
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main() { 


[ RERRKHHEKKKEKRKKEKKKK INITIALIZATION We te He He He We He Hee He We He He We He He He He We He ve We ve / 


/* Enable floating point exception handling */ 
enabl fpe (1) 


/* Initialize graphics software. */ 


if (gr_init() != NOERROR) 
rpt_err(FATAL,"ERROR: graphics init failed"); 


Now, you need to allocate space for both of the waveforms that you will use in 
this program. In general, all waveforms must be created (usually using 
create wf or createl_wf) before they can be the output of a SPD function. The 
exceptions to this rule are: 


1. The output of the acquisition functions (e.g. get2430() ) automatically create 
the output waveform. 


2. The arr_to wf() and arrl_to wf() functions create their own output 
waveform from the array provided as an input parameter. 


3. The file_to_wf(), afile_to_wf(), and df_to_wf() functions create waveforms 
based on the data they find in the disk file presented to them. 


The reason for not automatically creating output waveforms is that you may 
want to re-use an existing waveform. Also, many of the functions can’t predict 
what the size (or data type) of the output waveform should be. 


In this case, both waveforms are 8k points long and contain double precision 
floating point data. 


[RMR K RH WAVEFORM CREATION AND PROCESSING We We Ve ve He He ve ve ve He We Ye He He / 


/* Create a waveform data structures with space 
*allocated for a single tuple, single dimension of 
*single-precision type data. 


ay 


if (createl_wf ( (long)8192, W_DOUBLE, &wave) != NOERROR) 
rpt_err(FATAL,"ERROR: wave creation failed”); 


if (createl_wf ( (long)8192, W_DOUBLE, &wave2) != NOERROR) 
rpt_err(FATAL,"ERROR: wave2 creation failed"); 


Now, use the sinc() function to fill the already existing waveform 1 with data. 
Then, integrate waveform 1, putting the results into waveform 2. 


“Generate a sinc waveform. 
ampl = 10.0; 
freq = 0.04; 
pkpoint = 0.0; 
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dc = -0.03; 


if (sinc(ampl, freq, pkpoint, dc, wave) != NOERROR) 
rpt_err(FATAL, "ERROR: bsinc generation failed"); 


if (integrate(wave, EA_REPEAT, wave2) != NOERROR) 
6 rpt_err(FATAL,"ERROR: integrate generation failed"); 


The SPD Signal processing routines do not take care of scaling their own out- 
put. You must do this yourself. The table at the end of Section 4 shows the scal- 
ing requirements for each function. The function descriptions in Section 8 give 
detailed examples showing scaling and units processing code for every function 
that needs them. In the case of integration, the horizontal scale factor is carried 
along from the input to the output. The vertical values in the output must be 
multiplied by the input horizontal scale factor. 


hsf= dim_scale(wave, 0); 
dim_scale(wave2, 0) = hsf; 
we_mult(wave2, hsf, wave2); 


A curve is created in SPD graphics by plotting two data sets against each other. 

The SPD Waveform Graphics library lets you create data sets from SPD 

waveform structures or from floating point data arrays. In this example, the Y 

axis data is taken from the two waveforms you created using the gr_defw() func- 

tion. The X axis data set is an automatic data set created by giving the gr_defa() 
6 function the value of the first and last points on the X axis. 


[RRRKKHR KA DEFINE DATA SETS We We We We We We He We We He He We Ve We We We We He We He We We He We We Ye We ie He He / 


/* Associate range [0, 8191] with data set 0. */ 
setno = 0; 

startpt = 0.0; 

endpt = 8191.0; 


if (gr_defa (setno, startpt, endpt) != NOERROR) 
rpt_err(FATAL,"ERROR: data set 0 creation failed"); 


/* Associate wave data with data set 1 (Sinc waveform) */ 
setno = 1; 


if (gr_defw (setno, wave) != NOERROR) 
rpt_err(FATAL,"ERROR: data set 1 creation failed"); 


/* Associate wave data with data set 2 (Integrated waveform) */ 
setno = 2; 


if (gr_defw (setno, wave2) != NOERROR) 
rpt_err(FATAL, "ERROR: data set 2 creation failed"); 


Using the three data sets (one set of X values and two sets of Y values), define 
two curves with a legend for each. The legend presents a small segment of the 
line color and type that was defined for the curve along with the legend string 
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defined using the gr _Ignst() function. These calls are only definition functions. 
They do NOT cause the curves or legends to appear. 


[ REREHEHEKKKKKKEK DEFINE CURVE 1 Be He He He He Ve He te He te He He eH We He He He He He He He He He / 


/* Generate curve 1 using data set 0 for the X axis 
* and data set 1 for the Y axis. 
afd 

curvno = l; 

xsetno = 0; 

ysetno = 1; 


if (gr_curv (curvno, xsetno, ysetno, RED, INTRP) != NOERROR) 
rpt_err(FATAL, "ERROR: curve generation failed"); 


/* Define legend string */ 
if (gr_lgnst(curvno, "Sinec") != NOERROR) 
rpt_err(FATAL,"ERROR: in legend string definition") ; 


/* Generate curve 2 using data set 0 for the X axis 
* and data set 2 for the Y axis. 
wf 

curvno = 2; 

xsetno = 0; 

ysetno = 2; 


if (gr_curv (curvno, xsetno, ysetno, GREEN, INTRP) != NOERROR) 
rpt_err(FATAL,"ERROR: curve generation failed"); 


/* Define legend string */ 
if (gr_lgnst(curvno, "Integr(Sinec)") != NOERROR) 
rpt_err(FATAL,"ERROR: in legend string definition"); 


/* Define legend location */ 
if (gr_legnd(WHITE, UPPERRIGHT) != NOERROR) 
rpt_err(FATAL,"ERROR: legend definition failed"); 


To display the graph, first open one of the three device classes (DISPLAY, 
PRINTER, or PLOTTER) that SPD knows about. Each one corresponds to a 
CGI driver installed at boot time by means of a DEVICE statement in config.sys. 
This is followed by a gr_back() function call to select the background color. 
This call is optional. Its effect varies depending on the color capabilities of the 
device that you have opened. The three color values (rr,gg,bb) each take an in- 
teger value between 0 and 1000 where 1000 is full saturation for a color. In this 
example, an EGA display has a blue background. 


/ 40 te We He He We He He He He He He He He We He He DISPLAY WAVEFORMS W Fe He We He He We We He Fe He He Ve He ve We We ve ve He He ve / 


/* Select the CRT display device. */ 
if (gr_dev ("DISPLAY") != NOERROR) 
rpt_err(FATAL, "ERROR: device selection failed"); 


/* Set the background color. */ 

rr = 0: bb = 500: gg = 0 

if (gr_back(rr,gg,bb,status) != NOERROR) 
rpt_err(FATAL,"ERROR: background color failed"); 
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Now, tailor the graph (before displaying it) by adding axis labels, a title and sub- 
title, etc. 


/* Define grid type */ 
if (gr_grid(WHITE, DOTTEDGRID, WHITE, DOTTEDGRID) != NOERROR) 
rpt_err(FATAL, "ERROR: grid definition failed"); 


/* Label Y axis */ 
if (gr_ylabl("Volts" ,WHITE, status) 
rpt_err(FATAL,"ERROR: Y-label definition failed"); 


/* Label X axis */ 
if (gr_xlabl("Seconds", WHITE) != NOERROR) 
rpt_err(FATAL,”ERROR: X-label definition failed"); 


/* A Title */ 
if (gr_title("SPD Software" ,WHITE, status) 
rpt_err(FATAL,”"ERROR: graph title failed"); 


/* A Subtitle */ 
if (gr_stitl("by Tek" ,WHITE, status) 
rpt_err(FATAL, "ERROR: graph subtitle failed"); 


/* Draw box around graph */ 
if (gr_box(WHITE, status) 
rpt_err(FATAL,"ERROR: graph border failed"); 


/* Frame graph */ 
if (gr_frame(WHITE, status) 
rpt_err(FATAL, ERROR: frame generation failed"); 


Lastly, the graph is displayed on the screen. The call to gr_pause() causes the 
system to wait until a key is pressed before allowing the program to proceed. 


The call to gr_close() is not optional. Unlike a file close, which MS-DOS per- 
forms for you when your program terminates, gr_close() (besides closing down 
the graphics system) puts the display device back into character mode. Ending 
the program without calling gr_close() leaves your screen in graphics mode. 


[REKRMHHHEKKRKKKEKKKIK DISPLAY THE GRAPH We Fe Ve Ye We He He Ye He He We He Ve He ve He He He de we / 


/* Actually display the graph. */ 
gr_dsply(); 


/* Pause until the user presses ENTER. */ 
gr_pause(); 


/* Close the display device. */ 
gxr_close(); 


} 
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Using Multiple Viewports 


To display the two curves on separate sets of axes, you can graph and display 
one curve at atime. A program that does this is provided in source form as EX- 
AMPLE2.C on disk 4. It is the same as EXAMPLE1.C, except for the following: 


Having defined the first curve as in the first example, set the viewport ( the area 
in which graphic output occurs) to be the top half of the screen. The logical 
origin of the display device is the lower left corner of the display. Since the maxi- 
mum logical value in the X and Y direction is 32767, the upper right hand 

corner of the screen is at point (32767,32767) and the lower left hand corner of 
the viewport you want is at (0,16385). Physically, there are far fewer pixels on 
the screen than 32767, but the device independent graphics calls are automatical- 
ly translated into physical co-ordinates by the CGI device drivers. 


Note that you physically display the first viewport before going on to the second 
[RERKKKKKKEK DISPLAY THE GRAPH We He We We We de He He We He te He He He Ye We te We He We Ye tee Wee Hee He / 


/* Set the viewport */ 
if (gr_vwpt(0, 16385, 32767, 32767) != NOERROR) 
rpt_err(FATAL,”"ERROR: set viewport failed"); 


/* Actually display the graph. */ 
if (gr_dsply (status) 
rpt_err(FATAL,"ERROR: graph display failed"); 


To draw the other curve, you can re-use curve one rather than using another 
data structure. If you had used curve two, you would have to undefine the first 
curve to keep it from being displayed again in the new viewport. 


[ RRRRKKR KA HK KH HK REDEFINE CURVE 1 We He He We Ye He We He He He We He He He He He We We He eH He He He He He / 


/* Recreate curve 1 using data set 0 for the X axis 
* add data set 2 for the Y axis. 
*/ 


ysetno = 2 


if (gr_curv (curvno, xsetno, ysetno, GREEN, INTRP) != NOERROR) 
rpt_err(FATAL,"ERROR: curve generation failed"); 


/* Define legend string */ 


if (gr_lgnst(curvno, "“Integr(Sinec)") != NOERROR) 
rpt_err(FATAL,”"ERROR: in legend string definition"); 
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Now, you simply redefine the viewport to the lower half of the screen and re-dis- 
play. 


[RRR KK HK KKK KH REDISPLAY THE GRAPH We He We We We We He We Ye He He He We He Ve Ve He He eH / 

/* Set the viewport */ 

if (gr_vwpt(0,0, 32767,16384) != NOERROR) 
rpt_err(FATAL,"ERROR: set viewport failed"); 


/* Actually display the graph. / 
gr_dsply (); 
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Section 6 


SPD QuickBASIC 
Programming 


This section explains how to access the SPD functions from a QuickBASIC 4.0 
program. It assumes that you already know how to write QuickBASIC 
programs. Its purpose is to help you use the SPD functions to produce meaning- 
ful programs. In general, no attempt is made to give a detailed discussion of the 
parameter lists of the SPD functions. See Sections 8 through 11 for these details. 


The SPD QuickBASIC interface, SPDB.LIB, is an interface library that lets you 
use the SPD acquisition, signal processing, and waveform graphics libraries with 
Microsoft QuickBASIC 4.0 programs. Because of the ability to call Microsoft C 
from QuickBASIC 4.0, the same libraries are used with both languages. 
SPDB.LIB encapsulates the parts of the C interface that QuickBASIC can’t 
handle such as waveform structures and pointers, and makes the functions avail- 
able to you in an easy to use form. 


QuickBASIC Header Files 


The SPD QuickBASIC interface includes a set of header files that define the 
constants equivalent to those provided for C programming. These files are 
found in the \tek\spd\include directory. They can be identified by the .bi suffix. 
Constants such as colors (WHITE%, BLUE%, etc) that are needed for the 
graphics functions are provided. So are constants for signal processing functions 
such as window types for tapering (HAMMING%, BLACKMAN%, etc.). See 
Appendix C for a complete listing of these files. 


Besides providing helpful constant definitions, the header files also contain func- 
tional prototypes of all the SPD functions. Functional prototypes define the 
kinds of parameters that are required by the SPD functions. When functional 
prototypes are used, QuickBASIC can detect parameter mismatches in the com- 


Signal Processing & Display 6-1 


SPD QuickBASIC Programming 


pile step rather than at run time. This greatly speeds up debugging of SPD 
QuickBASIC programs. 


To use the header files (it’s strongly recommended), simply put the line 


' SINCLUDE: '\tek\spd\include\tekspd.bi' 6 


at the start of your program. The full path to the files is needed because 
QuickBASIC does NOT use the INCLUDE environment variable to find them 
as C does. 


QuickBASIC Function Names 


Because the rules for naming QuickBASIC variables differ from those for C, the 
function names are not identical. Given a C function name, however, you can 
easily derive the QuickBASIC name by removing all underscores and adding a 
"b" to the beginning. This rule holds for all QuickBASIC functions except those 
that replace the C waveform access macros. 


QuickBASIC Waveform Access Functions 


Since the C language waveform data structures are not directly accessible from 6 
QuickBASIC, direct manipulation of these structures cannot be accomplished by 

using the C waveform macros. However, all necessary operations are available 

to QuickBASIC by means of function calls. These functions are documented in 

Section 11, Waveform Structure Access. In some cases, a C macro can be used to 

read or write a value from a waveform structure. In these cases, you will find 

two QuickBASIC functions defined, one to read the variable and one to assign 

values to it. 


Waveform Data Structures 


A major programming difference between C and QuickBASIC occurs in 

referencing waveform data structures. In C, it’s done with a pointer to a 

memory location that holds the beginning of the data structure. In some cases, 

the C program actually uses a pointer to the pointer. In QuickBASIC programs, 

the reference in either case is a simple small integer that refers to an "instance" © 
of a waveform data structure. The interface routines create the waveform struc- 

tures for you and resolve the "indirect" referencing of waveform data structures. 

It is important to use small integers—start with number "0" and work up from 

there. If you use a large number, say "2000", the interface routine assumes that 
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sooner or later your program will be using 2001 waveforms (numbered "0" to 
"2000") and allocates memory to hold that many waveform pointers! 


One of the most helpful features of the QuickBASIC 4.0 interface is that all of 
the available memory can be used for SPD waveforms. QuickBASIC data, ex- 
cept dynamic arrays, is contained in the default data segment, and is therefore 
limited to 64k; but C data (all of the SPD waveform structures, graphics struc- 
tures, and the temporary arrays used by some SPD functions) uses the rest of 
memory. All of the details of interfacing NEAR and FAR pointers and other 
data items is done transparently for you in the interface library and via the func- 
tional prototypes. 


An exception to this storage arrangement occurs when you build an array of 
data under QuickBASIC and then associate that data with a SPD waveform 
using either of the barrtowf() or the barrltowf() functions. In those cases, the 
waveform data structure is located in C’s heap space but the array pointer is 
pointed at the QuickBASIC array. 


If you need to use dynamic arrays instead of static arrays, the situation changes 
somewhat. Dynamic arrays are NOT located in the default data segment, but 
must compete with the SPD functions for access to the rest of memory. This 
causes a conflict. The solution is to reserve space for the SPD data with the 
SETMEM() function. The parameter should be a negative number specifying 
how much memory should be reserved for the SPD C data structures. This num- 
ber should NOT include the QuickBASIC dynamic data arrays that you are put- 
ting into waveforms, but must include the data arrays of waveforms that will be 
read in from disk or acquired using the acquisition library. For example, if you 
need space for 250,000 bytes of C storage, the command | 


SETMEM(-250000) 


reserves it for you. See the QuickBASIC 4.0 BASIC Language Reference for 
more information about the SETMEM function. 


The QuickBASIC language doesn’t tolerate differing data types in an array, so 
the barrtowf() function allows you to specify only one tuple type even if you 
have more than one tuple in the QuickBASIC data array that is being put into a 
SPD waveform. Bwftoarr() extracts only one tuple at a time from a waveform. 
If a waveform has more than one tuple, you can use multiple calls to bwftoarr() 
using btupreorder() to control which tuple is extracted on each call. 


You can use berrfile() to redirect error messages to a file. (Note that berrfile() 


differs slightly from its C counterpart. You supply the file name as a string vari- 
able rather than through a file pointer.) You can also use the SPD brpterr() 
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function to print your own error messages to the same file as the SPD functions 
use. 


NOTE 


The descnptions in Section 8 for calling the functions from ® 
QuickBASIC sometimes use parameter names that are reserved 

words in QuickBASIC - e.g. out. The terms are used to show the 

compatibility with the C language calls. You should use different 

spellings or words. The QuickBASIC compiler will complain if 

you use reserved words improperly. 


The QuickBASIC Interface 


The QuickBASIC language interface, SPDB.LIB, coordinates memory manage- 
ment between the C libraries and your QuickBASIC program. 


To use the QuickBASIC interface, write your signal processing program using | 
the QuickBASIC calling format for the SPD functions. All QuickBASIC calling 
formats use the following general calling sequence: 


CALL bfunction (parameter list) 6 
where bfunction is the QuickBASIC calling format for the SPD function being 
called. (If you know the C function name, just drop the underscores and put a 
"b" in front.) The parameter list is a list of arguments separated by commas. 


The Structure of a SPD Program 


SPD applications usually contain the following sections: 


Generating or Acquiring waveform data 
Processing the waveform (FFT, convolution, etc.) 
Defining curves 

Controlling the appearance of the graph 


Displaying curves 


Storing waveforms on disk ®@ 


In your actual code, these sections may be clearly defined, interspersed, or em- 
bedded in loops or other program structures. For illustration purposes, they are 
treated as clearly separated sections. 
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Generating or Acquiring Waveform Data 


Waveform data in your application program can come from one or more of 
three possible sources: data acquired from an instrument into a data array, data 
read from a file, and/or waveforms generated by a SPD or user defined function. 


Acquired Data 


The acqm5S.lib acquisition library supplies functions that can be called from your 
programs to acquire waveforms from the same digitizers supported by 
SPDMENU. In fact, the parameters of the functions in acqmS.lib correspond 
exactly to the menu fields of the corresponding SPDMENU forms and provide 
the same functionality. With these functions, you do not need to allocate data 
arrays, request preamble data, or manipulate the data to get a fully normalized 
SPD waveform structure. All of the GPIB knowledge needed to acquire and 
scale waveforms for the supported Tektronix digitizers has been built into the ac- 
quisition functions. The following code fragment shows how to acquire a 
waveform from channel one of a Tektronix 2430 digitizer (the identifiers in capi- 
tals are constants defined in the header files): 


' SINCLUDE: '\tek\spd\include\tekspd.bi' 


waves = 1 
call bget2430(wave% ,WFLOATZ ,CH1% , POLLZ , T30SZ , TRUEZ , statusZ ) 
if status% <> 0 then 

call brpterr(status%,"Waveform acquisition failed."):end 
end if 


If the digitizer you are using is not supported by acqm5.lib, you can use a 
Tektronix-supplied package such as the GPIB QuickBASIC 4.0 interface library, 
or a package that you supply to acquire data from an instrument into a data 
array. This involves acquiring curve data as well as scale factors and offsets 
which you can apply to the acquired array. When the data has been placed into 
an array, you can use the barrltowf() function to create a SPD waveform struc- 
ture containing the data. 


The following code illustrates this process: 


*’ SINCLUDE: '\tek\spd\include\tekspd.bi’ 

dim sigarr! (1024Z) " use STATIC array when possible 
wavez = 1 

arrlen& = 1024 


" Load the array with data. For illustration purposes 
’ the array is filled with a ramp. 
for iz = 0 to arrlen& 
Sigarr!(iz4) = i2Z 
next iZ 
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' Convert the array to a waveform 
call barrltowf(sigarr!(0), arrlen&, WFLOAT%, wavez, status2Z) 
if statusZ <> 0 then 

call brpterr(status%,"Waveform acquisition failed."):end 


endif 
si @ 


The barrtowf() and barrltowf() functions, as well as all of the 
acquisition functions in acqm5.lib, allocate new memory for the 
waveform; so if the waveform passed to these functions already 
points to waveform data, the waveform ts re-assigned to point to 
the new waveform. This causes the old data to be lost and reduces 
the memory available to your program. 


If your program contains a loop that repeatedly uses one of these 
functions with the same waveform, be sure to free up the old 
memory with bfreewf() before re-using the waveform. 


Reading Waveforms from Disk Files 


If you have previously stored a waveform on disk using a SPD function or 

SPDMENJ, you can read it back in using bfiletowf() or bafiletowf(). Two 

routines are provided to be compatible with earlier versions of SPD which used ® 
proprietary and distinct formats for binary (bfiletowf) and ASCII (bafiletowf) 

waveforms. In the current version, these functions are simply two entry points 

to the same routine. They can read the following formats automatically by 

detecting the file format and using the appropriate instructions to read it: 


@ ADIF (Analog Data Interchange Format) ASCII 
@ ADIF binary 


ADIF is a new general purpose file format for expressing analog data. The 
details of this format are in Appendix E. 


NOTE 


Like the array-to-waveform functions, these functions allocate new 

memory for the waveform that is read from disk, so if the 

waveform pointer passed to these functions points to easting data, 

the old data ts lost and the memory available to your program ts 

reduced; so be sure to free up the old memory with bfreewf() ® 
before re-using a waveform. 


The following program fragment reads a file named my.wav into waveform 
wave: 
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" SINCLUDE: ‘\tek\spd\include\tekspd.bi' 
wavez = 1] 


" Read the data file into a working waveform 
call bafiletowf("my.wav", waveZ, status2Z) 
if statusZ <> 0 then 
call brpterr(status%,""Afile to waveform failed."):end 
endif 


If you want to read data that is in a non-standard format, the bdftowf() function 
lets you read the raw data from most disk files. Note that this function can only 
read point values; it does not know how to read scale factors, offsets, units 
Strings, etc. You specify the type of data in the file (ASCII, binary, or BASIC bi- 
nary), how many initial values to skip to bypass header information that the func- 
tion does not know how to process, and how many data values to skip between 
array values. After reading the file, use other SPD calls and macros to scale, 
label and title your waveform. 


Generating Waveforms with SPD Functions 


The SPD library also provides a number of functions which can generate sine 
wave, square wave, sine*, and sine(x)/x waveforms. In addition, uniform, binary, 
and gaussian random waveforms can be created. Detailed information about 
these functions is available in Section 8. 


NOTE 


These functions do not allocate space for the waveform. You must 
do this yourself using functions such as bcreatelwf(). 


The following program shows how waveform generation is accomplished. It is 
included on the distribution disks as simple.bas. The example will: 


@ create a one dimension, one tuple waveform 
@ fill the waveform with sine squared data (using sin2() ) 


@ display the resulting waveform (see later sections for discussion) 
' SINCLUDE: '\tek\spd\include\tekspd.bi' 


' Enable floating point exception handling. 
call benablfpe (1%) 


' Create a waveform data structure with space 
' allocated for a single tuple, single 
' dimension of single-precision data. 
length& = 256: wavez = 1 
call bcreatelwf (length&, WFLOAT%, wavez, status2Z) 
if status% <> 0 then 
call brpterr(status%,"Waveform creation failed"): end 
end if 
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' Generate a sin**2 waveform. 
ampl# = 10!: samples# = 40!: pkpoint# = 0!: dc# = 0! 
call bsin2(ampl#, samples#, pkpoint#, dc#, waveZ, status2Z) 
if statusZ <> 0 then 

call brpterr(statusZ,"Sin**2 generation failed"): end 
end if 


' Initialize graphics software. 
call bgrinit (statusZ) 
if statusz <> 0 then 
call brpterr(status%,"Graphics init failed"): end 


end if 


' Select the CRT display device. Other valid device names 
* are PRINTER and PLOTTER. A graphics driver for the device 
‘ must have been installed at boot time for bgrdev to work. 
call bgerdev ("“DISPLAY", status2Z) 
if status% <> 0 then 

call brpterr(status%,"Device selection failed"): end 
end if 


" Associate wave data with data set l. 
setnoz = 1 
call berdefw (setnoZ, wave%, status2Z) 
if status% <> 0 then 
call brpterr(status%,"Data set 1 creation failed"): end 
end if 


' Associate range [0, 255] with data set 0. 
setnoz = 0: startpt# = 0: endpt# = lengthé& 
call berdefa (setno%, startpt#, endpt#, status2Z) 


if status% <> 0 then 
call brpterr(status%,"Data set 0 creation failed"): end 


end if 


' Generate curve 1 using data set 0 for the X axis 
* and data set 1 for the Y axis. Set the line 
" color to white and the line type to solid. 
curvnoz = 1: xsetnozZ = 0: ysetnoz = 1 
call bgrcurv (curvno%,xsetnoZ,ysetno% ,WHITEZ , SOLIDZ, status ) 
if status%z <> 0 then 
call brpterr(status%,""Curve generation failed"): end 
end if 


' Actually display the graph. 
call bgerdsply (statusZ) 
if statusZ% <> 0 then 
call brpterr(status%,"Graph display failed"): end 
end if 


" Pause until the user presses ENTER. 
call bgrpause (statusZ) 


" Close the display device. 
call bgrclose (statusZ) 


end & 
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Processing the Waveforms 


Once you have one or more waveforms in memory, you can perform many types 
of processing on them. Some of the functions available are Fast Fourier Trans- 
forms (forward and inverse), waveform arithmetic (including complex arith- 

®@ metic), minimum and maximum, integration and differentiation, interpolation 
and decimation, etc. Many waveform manipulation functions are also available. 
A complete list of functions is found in Section 7. Function details are given in 
Section 8. 


The SPD Signal processing routines do not take care of scaling their own out- 
put. You must use SPD functions to scale the output waveform according to the 
table at the end of Section 4, which shows the scaling requirements of each func- 
tion. Detailed scaling and units processing examples are also included in the in- 
dividual function descriptions in Section 8. 


As an example, if you have acquired or read in a waveform wave%, the follow- 
ing code fragment converts it to the frequency domain and then to polar nota- 
tion: 


" SINCLUDE: '\tek\spd\include\tekspd.bi' 
wavez = 1 


rez = 2: imZ = 3 
6 mag% = 4: phasez = 5 


' Find the length (in points) of wavez 
call bwavelen(waveZ, lengthé&, status2) 
halflen& = (length&/2)+1 
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' Allocate space for rez and imZ 
call bereatelwf (halflen&, WFLOATZ, re%, statusZ) 
call bcreatelwf (halflen&, WFLOATZ, im%, status2Z) 


call brfft(wave%, reZ,im%, statusZ) 


’ Now scale brfft output 
' First, read the horizontal scale factor from wavezZ 
call brdimscale(waveZ,0%Z,hsf#,statusZ) 


" Calculate the new scale factor and vertical multiplier 
vscale# = hsf# 
hsfprime# = 1.0 /( length& * hsf# ) 


' Scale waveform reZ 


call bwdimscale(re%,0%,hsfprime#,status%Z) 
© call bwemult(re%,vscale#,realZ, statusZ) 


' Scale waveform im% 


call bwdimscale(imZ,0%,hsfprime#, status2Z) 
call bwcemult(im%Z,vscale#,imag2,statusZ) 
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’ Allocate space for mag%z and phasez 
call bereatelwf (halflen&, WFLOAT%, magz, statusZ) 
call bcreatelwf (halflen&, WFLOATZ, phaseZ, statusZ) 


call bpolar(reZ,im%,DEGREE% , TRUEZ , 0#,mag%, phase%, statusZ) © 


’ horizontal scale factor of reZ% --> mag%, phasez 
call bwdimscale(magZ,0%,hsfprime#,statusZ) 
call bwdimscale(phase%,0%,hsfprime#, status2) 


Notice the allocation of space for the resulting waveforms. In general, all 
waveforms must be created, usually using bcreatewf() or bcreatelwf(), before 
they can be the output of a SPD function. The exceptions to this rule are: 


1. The output of the acquisition functions (e.g. bget2430() ) automatically create 
the output waveform. 


2. The barrtowf() and barrltowf() functions create their own output waveform 
from the array provided as an input parameter. 


3. The bfiletowf(), bafiletowf(), and bdftowf() functions create waveforms based 
on the data they find in the disk file presented to them. 


The reason for not automatically creating output waveforms is that you may © 
want to re-use an existing waveform instead of creating a new one. Also, many 

of the functions can’t predict what the size (or data type) of the output 

waveform should be. 


Waveform Measurement 


SPD’s extensive waveform measurement capabilities, such as statistical and 
pulse measurements, are listed in Section 2 and detailed in Section 8. For ex- 
ample, given a waveform, wave, containing a pulse, the following program 
measures and prints on the screen, the amplitude, rise and fall times, overshoot, 
and undershoot. 


Calls are made to bplsedge() and bplsamp() to determine the top and bottom 

levels of the pulse. The reference point for the bottom of the pulse is defined as 

20 samples before the leading edge of the pulse. Once the top and bottom 

levels are known, the rise-time and fall-time are measured using bplsrtime() and 6 
bpisftime(). The pulse overshoot is measured by calling bplspospk() to deter- 

mine the peak value of the pulse. The percent overshoot is determined by relat- 

ing this value to the previously measured top and bottom values. 
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' SINCLUDE: '\tek\spd\include\tekspd.bi’ 


“wavez = 1 
dim farr#(4) ' fall-time parameter storage 
dim rarr#(4) ’ rise-time parameter storage 


dim tlevel#(3) ' proximal, mesial, distal levels 


" 10%, 50%, and 90% of pulse amplitude. 


' Define proximal, mesial, and distal points as 
© tlevel#[0] = 0.1: tlevel#[1] = 0.5: tlevel#[2] = 0.9 


' Obtain ‘wave’ here by acquisition, generation, file read, etc. 


' Measure the parameters of the pulse waveform with 
' bplsamp(), bplsedge(), bplsrtime(), bplstime() and 
' bplspospk(). Parameters to these routines are: 


lindex& = 20 ’ Start in from the end to avoid 
rindex& = 80 ‘ running past the end of the waveform. 
navi = 5 " Average 5 samples to determine level. 
nz = 3 * mumber of elements that must remain 


' above transition for it to be valid 


call bplsedge(wavez, lindex&, rindex&, RIGHT%, n%, REPEAT%Z, leadé&, 
trail&, lead2&, statusZ) 


call bplsamp(wave%z, lead&, trail&, lead& - 20, nav%, REPEAT%, 
top#, bot#, statusZ) 


call bplsrtime(wave%z, lindex&, rindex&, RIGHTZ, top#, bot#, nZ, 
REPEATZ, tlevel#(0), rarr#(0), statusZ) 


call bplsftime(wavez, lindex&, rindex&, RIGHT%, top#, bot#, nZ, 
REPEATZ, tlevel#(0), farr#(0), statusZ) 


call bplspospk (waveZ, lead&, trail&, pkloc#, pkval#, status%Z) 


' Print the results of the measurement 


print "PARAMETER MEASURED VALUE" 

pring “sewers eee ee mim mom mum moe ia 

print "Pulse Amplitude ", top# - bot# 

print "Rise-time ", varr#(0) 

print "Fall-time "| farr#(0) 

print "“Overshoot “, (pkval# - top#)/(top# - bot#) * 
100.;"%"0 

print "Peak Location ", pkloc# 


This results in the following output: 


PARAMETER MEASURED VALUE 
Pulse Amplitude 10.00 
Rise-time eS 

Fall-time 2.94 

Overshoot 3.34% 

Peak Location 35.30 
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Space Requirements 


Please be aware that some functions require a lot of intermediate storage and 

fail if that storage is not available. You can estimate the amount of memory 

taken by a waveform by multiplying the number of points in the waveform by @ 
four bytes for single precision data, and eight bytes for double precision data. 

Space requirements for the various functions are detailed in Section 8. 


As an example, to correlate two 4k point waveforms (single precision) using the 
bfcorr() function requires the following memory (the two temporary arrays are 
always double precision): 


inputs: 2waveforms * 4096 points * 4 bytes/point = 32,768 bytes 
temp: 2waveforms * 8192 points * 8 bytes/point = 131,072 bytes 
Output: lwaveform * 4096 points * 4 bytes/point = 16,384 bytes 
TOTAL 180,224 bytes 


Sub-waveforms 


If you are working with multi-dimension or multi-tuple waveforms, remember 
that most SPD functions work only on the first dimension or tuple. To access 
other dimensions, use the bdimreorder() function. The btupreorder() function 
allows you to re-sequence the tuples in a waveform so that the one you want is 
first. 


These functions together with bzonedim() can be used to create a sub-section of 
a waveform. 
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The following program illustrates a procedure for examining a part of the 
waveform array using the SPD functions. In this example, a section of a two 
dimensional 4 x 10 waveform is examined. The area to be isolated is row 2, 
columns 2 through 7. This is shown pictorially as: _ 


Column 


Fig. 64. Array created with create_wf(). 


Column 
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Fig. 6-2. Shaded area indicates elements pointed to by 
subwave after first call to zone_dim/(). 


Column 
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Fig. 6-3. Shaded arca indicatcs clements pointed to by 
subwave after second call to zone_dim(). Subwave created 


by first call to zone_dim() has been deleted (by using 
DELETE option). 


The SPD functions bdimreorder() and bzonedim() are used to isolate the sub- 

section of the waveform. This is accomplished by first making a subordinate 

waveform, "subwave", that consists of data from row two. This is done in the 

first call to bzonedim(). The next step is to reduce the number of columns to in- 

clude only columns two through seven. This is accomplished in the second call to 

bzonedim(). Finally, the two dimensional waveform is converted to one dimen- 
@ sion by bdimreorder(). The program fragment ts: 


' SINCLUDE: '\tek\spd\include\tekspd.bi’ 
wavez = 1: subwaveiz = 2 


dim tarrZ(1) 
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dim order%Z(1) 
dim darr&(2) 


' * Create the two dimensional 4 x 10 waveform 

. mt 4 rows -- dimension 0 

‘ # 10 columms -- dimension 1 

ndz = 2 @ 
tarr%(0) = WDOUBLEZ 

darr&(0) = 4 

darr&(1) = 10 


call bcreatewf(nd%,darr&(0),1%,tarrZ(0),wavez,errZ) ‘see Fig. 1 

' whee load the waveform with data here *** 

' * Subsection the waveform array. 

call bzonedim(wavezZ, 0%,2&,2&,KEEP%, subwaveZ,err%) ' see Fig. 2 
call bzonedim(subwave% ,1%,2&,7&,DELETE%, subwave%,err%Z) ' see Fig. 3 
" * Reorder the waveform into a one dimension waveform 

order%Z(0) = 1 

newndz =] 


call bdimreorder(subwave% ,newndZ,order%Z(0) ,DELETE%, subwavez, errZ) 


' * Perform operations on the subsection of the waveform 
' * by using subwave. 


Note that only the original wave and the final subwave data structures remain. 
The intermediate subwave structures are deleted using the DELETE keyword in 
the calls to bzonedim() and bdimreorder(). 


SPD Graphics 


In order to display a waveform using the SPD graphics functions, you must per- 
form the following steps, each of which is discussed in subsequent sections: 
initialize the graphics system 

define the curves 


customize the appearance of the graph (optional) 


display the graph 


Initialize the Graphics System 


must call bgrinit(), which initializes the variables in the graphics subsystem to 


Before performing any other graphics calls (functions starting with bgr) you ® 
their default values. This function has no parameters. 


6-14 Signal Processing & Display 


SPD QuickBASIC Programming 


Define the Curves 
Two steps are required to produce a curve from your data. 


Step 1: Data sets for the X values and for the Y values must be defined using 
one of the following functions: 


bgrdefa() - automatic generation of a set, given the starting and ending 
points 


bgrdefd() - from an array of doubles 
bgrdeff() - from an array of float values 
bgrdefw() - from the first dimension and tuple of a waveform 


Typically, the X data set is defined using bgrdefa(), which defines a data set 
based on the end points. The end points are double precision floating point 
numbers, so by using the first and last scaled X values as endpoints, the data set 
is scaled automatically. It is also possible to define the X data set from a 
waveform or a numeric array. This might be done if you have acquired data in 
XY mode from a digitizer. 


The X axis definition from simple.bas is: 
call bgrdefa(0%, 0.0#, DIMLENGTH# - 1.0, status2Z) 


The Y values are usually generated from a waveform with bgerdefw(), since 
waveform structures are required by the signal processing functions, but you can 
also use bgrdeff() or bgrdefd() to create data sets directly from numeric arrays. 


The Y axis data set definition from simple.bas is: 
call bgrdefw(1%, wave%Z,status2Z) 


Step 2: A curve is defined as one data set on the X (independent) axis versus 
another set on the Y (dependent) axis. Any number of curves can be defined 
and are displayed together on the same axes later when bgrdsply() is called. The 
function bgrcurv() allows selection of line color and style (dejagged, interpo- 
lated, solid, or one of several dot/dashed patterns). A similar function, 
bgrmrkr() generates a curve displayed as markers, rather than lines.. 


In the above examples, the data set number (first parameter) of the X axis data 


is 0 and the data set for the Y axis data is 1. The data set numbers are used by 
bgrcurv() to obtain the X and Y data. 
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The curve definition from simple.bas is: 


call bgreurv(1%, 0%, 1%, WHITEZ, INTERPZ, status2%) 


where WHITE% and INTERP% are pre-defined constants from the header files 
tekgr.h specifying the curve color and line style. INTERP% specifies an interpo- 
lated line style. 


The graphing library automatically scans the data for minimum and maximum 
values and generates the axis ticks and labels using these values, unless the 
graph limits have been explicitly set using bgrxrang() or bgryrang(). Data ex- 
ceeding the specified graph limits is not displayed. (Automatic scaling is based 
on the input data values. The interpolated display generation adds data values 
that may be outside the range of the input data - the result may be a clipped dis- 
play. (Use manual scaling, bgrxrang() or bgryrang(), in this case.) 


Curves can be added to an existing display by using bgraddcv() and bgraddmk(), 
as long as the viewport is not changed. Data sets and curves can be redefined 
whenever needed, although redefining datasets does not automatically redefine 
the curve that uses them; you must call bgrcurve() or bgrmrkr() again. You 
can also undefine data sets and curves by using bgrundef() and bgruncrv(). 


Using bgrtype(TEXTONLY®%) generates a graphic display consisting only of 
text, if text only is specified. In this mode, text notes defined by bgrtext() are 
the only graphic output. Bertype(DISPLAYGRAPH®) resets the system to dis- 
play graphics again. 


Customize the Appearance of the Graph (Optional) 


Functions are provided to include a title, subtitle, x and y axis labels, and a 
legend; separate colors can be specified for each. The major (labeled) and 
minor (unlabeled) tick mark spacings can be specified for each axis. 


The background color of your display can be modified by calls to berback(). The 
three integer parameters specify the mix of red, green, and blue in the back- 
ground color. The actual color that appears on the screen depends on which 
CGI device driver is being used to display graphics on the screen. Please note 
that the effect of bgrback() is on the entire display not simply on the current 
viewport. It takes effect when you invoke bgrdsply(). 


By default, the entire graphic display area is used to display a graph. However, 
the function bgrvwpt() allows specification of a viewport within the display, al- 
lowing multiple graphs per display. The viewport area can be outlined using 
berframe(). A box can be drawn around the graph area alone with bgrbox(). 
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Displaying the Graph 


SPD graphics display occurs between calls to bgrdev(), which opens the device 
specified by the parameter, and bgrclose() which closes the device. If the device 
specified in bgerdev() is "DISPLAY", the screen is switched from text mode to 
graphics mode. Similarly, bgrclose() returns the screen to text mode. As a side 
effect, both calls clear the screen. The currently defined graph is output by the 
function bgrdsply(). The viewport area is first cleared and then the graph and 
associated text are drawn. Since only the viewport is cleared, careful use of curve 
definition followed by bgrvwpt() and bgrdsply() allows multiple graphs to be dis- 
played at once. 


The function bgrupdate() uses the current data and curve definitions to re-draw 
only that part of the graph containing the curves. The current data and curve 
definitions can be different from those used when the entire graph was drawn 
using bgrdsply(); the window range remains the same. If any newly defined data 
is outside the window, it is clipped. The window is not recalculated, since this 
would require re-drawing the axes, tick marks, and labels. Specifying a new 
graphics device does not affect the currently defined graph. Thus, a graph can 
be sent to a plotter by the following function calls: 


call bgrinit() ' Initialize the graphics 


' curve definition and graph customization 
" calls go here 


call bgrdev("PLOTTER", statusZ) ' open the plotter (could be 
* PRINTER or DISPLAY too 


call bgrdsply(statusZ) ' output the graph 


call bgrclose(statusZ%) ' close the display device 


NOTES 


I. Your CONFIG.SYS file must contain statements loading the 
proper graphics device drivers for the display, printer, or plotter that 
you wish to use. See Section 2, Getting Started, for details. 


2. When berdev() ts executed with an argument of "DISPLAY", 
your screen goes into graphics mode. From that point until 
bgrclose() ts called, text written to the screen will appear in un- 
usual colors and with possible side effects. We suggest that you do 
not use this approach. 
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Figure 6-4 shows the graphic output of simple.bas. 


Fig. 6-4. Simple.bas graph. 


Storing Waveforms on Disk ® 


Besides displaying the graphs, you may also want to save your waveforms on 
disk. The functions bwftofile() and bwftoafile() store waveforms on disk. 
Bwftoafile() stores the waveform as an ADIF ASCII file; that is, the numeric 
values are stored as ASCII strings and are human readable. Bwftofile() uses the 
ADIF binary format in which numeric values are stored in binary form. 


For example, the following command writes the ramp waveform created above 


to an ASCII ADIF file named "ramp.wav". 
call bwftoafile(wave%, "“ramp.wav", statusZ) 
The resulting file would look like this: 


ADIF ( STD ( VERSION 0.99 ) | 


IDENTIFY ( 
SOURCE (PACKAGE "SPD V2.2") | 
DATE "1988-10-06" | 
, TIME "13:09:27" © 
) 
DIM=X1 ( 
TYPE IMPLICIT | 
SCALE 1 | 
OFFSET 0 | 
SIZE 16 
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» | 
DIM=Y2 ( 
TYPE EXPLICIT | 
SCALE 1 
OFFSET 0 | 
ENCODE (HIRANGE 3.40282e+038) 


» | 

TRACE=SPD1 ( 
INDEPENDENT (DIM (LABEL X1) ) | 
DEPENDENT (DIM (LABEL Y2) ) | 


) | 
DATA ( CURVE ( VALUES 


= = = 


~~ = 7. 


OOnNMUN SF WN-H O 


ADIF files can be loaded into an SPD waveform structure by using the 


bfiletowf() function. See Reading Waveforms from Disk Files earlier in this sec- 
tion. 
Compiling and Linking a QuickBASIC Program 


When using QuickBASIC 4.0 with SPD, it is necessary to use the command line 
compile and link method rather than the QuickBASIC interactive environment. 


This is due to the fact that the SPD libraries, when made into a Quicklib for use 


in the environment, simply will not fit into 640K with the QuickBASIC environ- 
ment, much less allow any room for a user program. 


The following example demonstrates the necessary steps to compile a 


QuickBASIC source code program called, for example, FOO.BAS. It assumes 
the QuickBASIC compiler, BC.EXE, is in a directory that’s named in the PATH 
environment. 


be /ah /o foo; 


A batch file, QB4COMP.BAT, which invokes QuickBASIC in this way, is 


provided on disk 7. The /o flag means that this program will be linked into a 
freestanding program which does not need the QuickBASIC runtime library to 
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be present to run. If you want to use the runtime library, omit the flag. The /ah 
flag allows dynamic arrays to be larger than 64k. 


To link the compiled QuickBASIC program (FOO.OBJ) with the necessary 
program objects and directories, the following command could be entered (on 
one line!): 


link /E /SE:256 /NOE /NOD /STACK:12000 
footc: \tek\spd\lib\fpem5, foo, ,spdbtacqm5+grm5+spdm5tbcom40 


where fpem5 is the floating point exception handler, and the list of libraries in- 
cludes: 


SPDB.LIB - the QuickBASIC interface to the other SPD libraries 
ACQMS.LIB - The SPD Acquisition Library 

GRM5S.LIB - The SPD Waveform Graphics Library 

SPDMS.LIB - The SPD Signal Processing Library 


BCOM40.LIB - The QuickBASIC 4.0 alternate run time library 


NOTE 
BECAUSE OF FUNCTIONAL DEPENDENCIES BETWEEN _ 
THE LIBRARIES, IT IS NECESSARY THAT THE LIBRARIES 
BE SPECIFIED IN THE ABOVE ORDER. MODIFYING THE 
ORDER MAY RESULT IN UNRESOLVED EXTERNAL 
REFERENCES 


Since this command is provided in a batch file named QB4LINK.BAT, all you 
need enter to link FOO.OBJ is: 


QB4LINK FOO 


When linking QuickBASIC programs, use the linker provided with that version 
of QuickBASIC, not one provided with DOS or another compiler. The flags in 
the link command are: 


/E causes the .EXE file produced to be packed as if the EXEPACK utility 
had been run on it. 


/SE:256 sets the maximum number of segments to 256. If you are linking an © 


especially complex system and you get a message that you have "too many seg- 
ments" try increasing the 256 to a larger number. 
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/NOE tells the linker to search the C libraries only if the reference is not 
resolved within QuickBASIC. 


/NOD specifies that no default library search is to be performed. This is im- 
portant, since some SPD routines call for the C run time libraries. The func- 
tions they are looking for have been built into the SPD libraries, but this switch 
keeps the linker from trying to look in the wrong place. 


/STACK:12000 specifies that 12000 bytes should be reserved for the program 
stack. 


For even easier operation, the contents of QB4COMP.BAT and QB4LINK.BAT 
have been combined into a file called QB4.BAT. 


The BCOM40.LIB is the QuickBASIC library used to create freestanding 
programs that don’t need the runtime library present to run. If you want to use 
the runtime library instead, change QB4LINK.BAT to refer to BRUN4O0 instead 
of BCOM40. You must also remove the /o flag from the QB4COMP.BAT com- 
pilation batch file. 


If you have QuickBASIC 4.00b, modify the link line of QB4.BAT and 
QB4LINK.BAT to refer to BCOM41.LIB or BRUN41.LIB 


If you are linking your programs on a dual diskette system without a hard disk, 
you will find that the libraries do not fit on a single diskette. In this situation, 
alter the QB4LINK.BAT to refer to drive b:. When a library is not found, the 
linker will ask you to provide an alternate directory for the library. At this 
point, insert the new disk with the library that the linker is looking for in drive b: 
and press RETURN. 


SPD Function Return Values 


Nearly all SPD functions return a status% variable which notifies the calling 
program of the success or relative failure of the function call. If an error occurs 
in a SPD function, messages that describe the error are sent to the screen (un- 
less redirected to a file by the berrfile() function.) The messages identify the 
called SPD routine that was responsible, even though the actual error may have 
been discovered by a function that’s deep within the SPD libraries. It’s wise for 
the user application to check the return value from a call to a SPD function. 
Messages that return a status of WARNING% generally advise that some action 
was taken that may or may not be expected, but the results of the operation may 
be suspect. A FATAL% status indicates that the operation failed for some 
reason and the results, if any, are invalid. CRASH% errors are serious; con- 
tinued execution of the program could cause deleterious effects. 
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Error Messages 


While in graphics mode (between calls to bgrdev() and bgrclose()), error mes- 

sages may not reach the screen or, if they do, may not be recognizable (in fact, 

they may mangle graphic output). You should redirect error messages to a file 

during graphic display portions of your program using the berrfile() function, @ 
and then look at that file afterwards. 


Error messages, both those in the SPD libraries and those that your program 
generates with the brpterr() function, precede the error message text with a call- 
ing list of functions that help you locate just where the error occurred. Use of 
the bseterr() and bclrerr() functions allows you to insert and remove names of 
your functions or program sections from the function list printed with error mes- 
sages. 


Floating Point Errors 


The SPD signal processing library intercepts floating point errors that occur in 
SPD library routines and provide reasonable substitute results. If you run the 
benablfpe() function, these interceptions are counted and reported along with 
other standard errors until you invoke the bdisablfpe() function. & 


General Limits 


The following general limits govern the use of SPD with QuickBASIC programs: 


@ Up to 32 data sets can be defined (numbered 0-31). The amount of 
data stored is limited by the amount of available memory. 


@ Up to 32 curves can be defined at one time (numbered 0-31) 


@ Titles, labels, and text strings can have a maximum of 128 characters 
each. 


@ A maximum of 48 text notes can be defined at one time. 


@ The largest single precision floating point waveform that you can suc- 
cessfully process with brfft() or correlate with itself is 8192 points. This 
limitation is due to the large amount of temporary storage needed for 
these functions. If you have a large number of waveforms in memory, 
have memory resident software (besides your SPD program), or use G 
double precision data, the maximum size you can process may be less 
than 8192 points. 
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Example QuickBASIC Programs 


The following complete example QuickBASIC program incorporates most of 
the information discussed above. It creates two waveform data structures, fills 
the first with a sine(x)/x function, integrates the first waveform putting the 
results in the second, and displays both waveforms on one set of axes. A varia- 
tion discussed later on displays both waveforms in separate viewports. 


This program is provided in source form as EXAMPLE1.BAS on disk 4. The 
variation is stored as EXAMPLE2.BAS. Each section is discussed, in turn. 


The first line of the program is an SINCLUDE metacommand that brings in the 
QuickBASIC version of the SPD include files. (See the listing in Appendix C.) 
This should be the first line of any QuickBASIC program that uses the SPD 
functions. Then the floating point exception handler is enabled by a call to 
benablfpe(). The last piece of initialization is to call the bgrinit() function 
which initializes the SPD graphics data structures and status variables. This 
function should be called before any other SPD graphics calls are made. 


’ SINCLUDE: ‘'\tek\spd\include\tekspd.bi' 


9 We ve de He Ye Ye de te ve de ve de We We ¥e Ye He He ve INITIALIZATION te te Ye Ye Fe Fe te Ye te te te ve Ye ve te Fe de Fe He Ye te Ye ve Ye 


"Enable floating point exception handling. 
call benablfpe (12%) 


"Use error file instead of screen 
call berrfile("examplel.bas",status2Z) 


‘Initialize graphics software. 
call bgrinit (status2Z) 
if status% <> 0 then 
call brpterr(status%z," graphics init failed"): end 
end if 


Now, you need to allocate space for both of the waveforms that you will use in 


this program. In general, all waveforms must be created (usually using 
bcreatewf or bcreatelwf) before they can be the output of a SPD function. The 
exceptions to this rule are: 


1. The acquisition functions, such as bget2430(), automatically create the out- 
put waveform. 


2. The barrtowf() and barrltowf() functions create their own output waveform 
from the array provided as an input parameter. 


3. The bfiletowf(), bafiletowf(), and bdftowf() functions create waveforms based 
on the data they find in the disk file presented to them. 
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The reason for not automatically creating output waveforms is that you may 
want to re-use an existing waveform. Also, many of the functions can’t predict 
what the size (or data type) of the output waveform should be. 


In this case, both waveforms are 8k points long and contain double precision 
floating point data. 
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"Create a waveform data structures with space 
‘allocated for a single tuple, single dimension of 
"single-precision type data. 

length& = 8192&: waveZ = 1: wave2% = 2 


call bcreatelwf (length&, WDOUBLE%, wave%, status2Z) 
if status% <> 0 then 

call brpterr(status%," wave creation failed"): end 
end if 


call bcreatelwf (length&, WDOUBLE%, wave2%, status2Z) 
if status%z% <> 0 then 

call brpterr(status%," wave2 creation failed"): end 
end if 


Now use the bsinc() function to fill the already existing waveform 1 with data. 
Then integrate waveform 1, putting the results into waveform 2. 


‘Generate a sinc waveform. 6 
ampl# = 10.0#: freq# = 0.04#: pkpoint# = 0.0#: dc# = -0.03#4 


call bsinc(ampl#, freq#, pkpoint#, dc#, wave%, statusZ) 
if status% <> 0 then 

call brpterr(status%," bsinc generation failed"): end 
end if 


call bintegrate(wavez , REPEAT% , wave2% , status%Z ) 
if status% <> 0 then 


call brpterr(status%," integrate generation failed"): end 
end if 


The SPD Signal processing routines do not take care of scaling their own out- 

put. You must do this yourself. The table at the end of Section 4 shows the scal- 

ing requirements for each function. The function descriptions in Section 8 give 

detailed examples showing scaling and units processing code for every function 

that needs them. In the case of integration, the horizontal scale factor is carried 

along from the input to the output. The vertical values in the output must be 

multiplied by the input horizontal scale factor. _ 


call brdimscale(wave%, 0%, hsf#, status2Z) 
if statusZ% <> 0 then 

call brpterr(status%," brdimscale failed"): end 
end if 


call bwdimscale(wave2%, 0%, hsf#, statusZ) 
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if status% <> 0 then 

call brpterr(status%," bwdimscale failed"): end 
end if 
call bwemult(wave2Z, hsf#, wave2%, statusZ) 
if status% <> 0 then 

call brpterr(status%," bwemult failed"): end 
end if 


r A curve is created in SPD graphics by plotting two data sets against each other. 
The SPD Waveform Graphics library lets you create data sets from SPD 
waveform structures or from floating point data arrays. In this example, the Y 
axis data is taken from the two waveforms created using the berdefw() function. 
The X axis data set is an automatic data set created by giving the bgrdefa() func- 
tion the value of the first and last points on the X axis. 
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"Associate range [0, 8191] with data set 0. 
setnoz = 0: startpt# = 0.0#: endpt# = 8191.0# 


call berdefa (setnoz, startpt#, endpt#, status2Z) 
if statusZ <> 0 then 

call brpterr(status%," data set 0 creation failed"): end 
end if 


‘Associate wave data with data set l. 
setno% = 1: wavez = 1 


call bgrdefw (setnoZ, wave%, status%) ' Sinc waveform 


if status% <> 0 then 
call brpterr(status%," data set 1 creation failed"): end 


end if 


‘Associate wave data with data set 2. 
setnoz = 2: wavez = 2 


call bgrdefw (setnoZ, wave%, status%) ' Ingrated waveform 
if status% <> 0 then 

call brpterr(status%," data set 2 creation failed"): end 
end if 


Using the three data sets (one set of X values and two sets of Y values) we now 
define two curves along with a legend for each. The legend presents a small seg- 
ment of the line color and type that was defined for the curve, along with the 
legend string defined using the bgrignst() function. These calls are only defini- 
tion functions. They do NOT cause the curves or legends to appear. 
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"Generate curve 1 using data set 0 for the X axis 

‘and data set 1 for the Y axis. 

curvnoz = 1: xsetnoZz = 0: ysetnoz = 1 


@ call bgrcurv (curvnoZ, xsetno%, ysetnoZ, REDZ, INTERPZ, statusZ) 
if status% <> 0 then 
call brpterr(status%," curve generation failed"): end 
end if 


‘Define legend string 
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call bgrlgnst(curvno%, "Sinec", status2Z) 
if status%<> 0 then 

call brpterr(status%," in legend string definition" ):end 
end if 


"Generate curve 2 using data set 0 for the X axis 
‘and data set 2 for the Y axis. 
curvnoz = 2: xsetnoz = 0: ysetnoz = 2 


call bgrcurv (curvno%Z, xsetnoZ, ysetnoz, GREEN%, INTERP%, statusZ) 


if statusZ <> 0 then 
call brpterr(statusZ," curve generation failed"): end 
end if 


‘Define legend string 
call bgrlgnst(curvno%, "Integr(Sinec)", status2Z%) 
if statusZ<> 0 then 
call brpterr(statusZ," in legend string definition" ):end 
end if 


‘Define legend location 
call bgrlegnd(WHITEZ, UPPERRIGHTZ, status2Z) 
if status%<> 0 then 
call brpterr(status%," legend definition failed" ):end 
end if 


To display the graph, first open one of the three device classes (DISPLAY, 


PRINTER, or PLOTTER) that SPD knows about. Each one corresponds to a 
CGI driver installed at boot time by means of a DEVICE statement in config.sys. 


This is followed by a bgrback() function call to select the background color. 


This call is optional. Its effect varies depending on the color capabilities of the 
device that you have opened. The three color values (rr,gg,bb) each take an in- 
teger value between 0 and 1000, where 1000 is full saturation for a color. In this 


example, an EGA display has a blue background. 
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‘Select the CRT display device. 
call bgrdev ("DISPLAY", status2Z) 
if status% <> 0 then 
call brpterr(status%," device selection failed"): end 
end if 


‘Set the background color. 
rrz = 0: bb% = 500: ggz = 0 
call bgrback(rr%,ggZ,bb%, status2Z) 
if statusz% <> 0 then 
call brpterr(status%," background color failed"): end 
end if 


Now, let's tailor the graph (before displaying it) by adding axis 


labels, a title and sub-title, etc. 


"Define grid type 


call bgrgrid(WHITE%, DOTTEDGRID%, WHITE%, DOTTEDGRID%, statusZ) 


if status%<> 0 then 
call brpterr(status%," grid definition failed"):end 
end if 


‘Label Y axis 
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call bgrylabl("Volts",WHITEZ, status2Z) 
if status%<>0 then 

call brpterr(status%," Y-label definition failed") :end 
end if 


‘Label X axis 
call bgrxlabl("Seconds", WHITE%, status2Z) 
if statusZz<>0 then 
call brpterr(status%," X-label definition failed"):end 
end if 


‘A Title 
call bgrtitle("SPD Software" ,WHITE%Z, status) 
if status%<>0 then 
call brpterr(status%," graph title failed"):end 
end if 


‘A Subtitle 
call bgerstitl("by Tek" ,WHITEZ, status2Z) 
if status%<>0 then 
call brpterr(status%," graph subtitle failed"):end 
end if 


*Draw box around graph 
call bgrbox(WHITEZ, status2Z) 
if statusZz<>0 then 
call brpterr(statusZ," graph border failed”):end 
end if 


‘Frame graph 
call bgrframe(WHITE%, status2Z) 
if status%<>0 then 
call brpterr(status%Z," frame generation failed"):end 
end if 


Lastly, the graph is displayed on the screen. The call to bgrpause() causes the 
system to wait until a key is pressed before allowing the program to proceed. 


The call to bgrclose() is not optional. Unlike a file close, which MS-DOS per- 
forms when your program terminates, bgrclose() (besides closing down the 
graphics system) puts the display device back into character mode. Ending the 
program without calling bgrclose(), leaves your screen in graphics mode. 
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‘Actually display the graph. 
call bgrdsply (status%Z) 
if status%z% <> 0 then 
call brpterr(status%," graph display failed"): end 
end if 


"Pause until the user presses ENTER. 
call bgrpause (status2Z) 


‘Close the display device. 
call bgrclose (status2Z) 


end 
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Using Multiple Viewports 


To display the two curves on separate sets of axes, you can graph and display 

one curve at a time. A program that does this is provided in source form as EX- 
AMPLE2.BAS on disk 4. It is the same as EXAMPLE1.BAS, except for the fol- @ 
lowing: 


Having defined the first curve as in the first example, set the viewport (the area 
in which graphic output occurs) to be the top half of the screen. The logical 
origin of the display device is the lower left corner of the display. Since the maxi- 
mum logical value in the X and Y direction is 32767, the upper right hand 

corner of the screen is at point (32767,32767) and the lower left hand corner of 
the viewport you want is at (0,16385). Physically, there are far fewer pixels on 
the screen than 32767, but our device independent graphics calls are automatical- 
ly translated into physical co-ordinates by the CGI device drivers. 


Note that you physically display the first viewport before going on to the second 
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"Set the viewport 
call bgrvwpt(0%, 163852, 32767%, 327672, statusZ) 
if statusZz% <> 0 then 


call brpterr(status%," set viewport failed"): end 
end if 


"Actually display the graph. 
call berdsply (statusZ) 
if statuszZ <> 0 then 
call brpterr(status%," graph display failed"): end 
end if 


To draw the other curve, you can re-use curve one rather than using another 
data structure. If you used curve two, you would have to undefine the first curve 
to keep it from being displayed again in the new viewport. 
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"Recreate curve 1 using data set 0 for the X axis 
"and data set 2 for the Y axis. 
ysetnosz = 2 


call bgrcurv (curvno%Z, xsetnozZ, ysetno%, GREEN%Z, INTERP%, status2Z) 
if status% <> 0 then 
call brpterr(status%," curve generation failed"): end 


end if 
"Define legend string 6 


call bgrlgnst(curvnozZ, "Integr(Sinec)", status%Z) 
if statusZ<> 0 then 

call brpterr(status%," legend string definition" ):end 
end if 
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Now, simply redefine the viewport to the lower half of the screen and re-display 
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"Set the viewport 
call bgrvwpt(02,0%, 32767%,16384%, statusZ) 


if status% <> 0 then 
call brpterr(status%," set viewport failed"): end 


end if 


"Actually display the graph. 
call bgerdsply (statusZ) 
if statuszZ <> 0 then 
call brpterr(statusZ," graph display failed"): end 
end if 
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Section 7 


An Overview of the 
SPD Functions 


The SPD Functions 


This section introduces you to the SPD functions, listing them by function 
categories and. briefly explaining their purpose. Use this section as a quick 
reference to find the function or functions that meet your needs. For informa- 
tion on using the SPD functions in your programs, see Sections 5 and 6 of this 
manual. More detailed information on specific functions can be found in Sec- 
tions 8, 9, and 10. 


The functions fall into four major categories as shown below and in Figure 7-1. 


@ Waveform Creation, Acquisition, and I/O Functions 
@ Waveform Processing Functions 
@ Waveform Graphic Display Functions 
@ Waveform Data Structure Manipulation Utilities 
The functions are listed by their C language spelling. The QuickBASIC spelling 


can be obtained by dropping the underscores and prepending a ‘b’. Almost all 
of the functions are available through the SPDMENU interface. 
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Figures 7-2 through 7-5 list the functions that fall into each of these categories. 
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Fig. 7-1. The SPD functions. 
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GENERATION, 
ACQUISITION, AND 
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copy _wf 
create wf 
createl wf 


Signal Generation sin2 
sinc 
sinewave 
Copy/Create Waveform 
free_wf 
make target 


squarewave 
" afile to wf 
File l/O df on we 


file to wf 
Waveform Array 
Manipulation 


wf_to afile 
wf_to file 
Waveform Acquisition 
Functions 


arr_to wf 
arrl_to wf 
wf_to_array 


getllk 

get2220 
get2230 
get2430 
getS223 
get7854 
get7912 
get7d20 
getRTD 


Fig. 7-2. Waveform generation, acquisition, and I/O functions. 
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WAVEFORM 
PROCESSING 
FUNCTIONS 


7-4 


cpx_add w_add wc_add w_exp 
cpx_sub w_sub wc_sub w_log 
cpx_mult w_mult we_mult w_sqrt 
cpx_div w_div wc_div w_power 
polar w_min wc_min 
rectang w_max wc_max 
Frequency Domain | fit rfft 
Conversion ifft taper 
irfft 
Convolution/ convolve 
Correlation fconv 
fcorr 
Differentiation diff 
Data Interpolation/ | w_ decimate 
Decimation w_interp 
Random Number | randb 
Generation randg 
randu 
FIR Filter 
Generation eq_fir 
Statistical meanstd 
Measurement nee 
sumave 
. Sinewave Parameter sisi deee te 
Measurement 
Pulse Parameter pls amp pis ftime pls_negpk pls_pkfind 
plis_calc pls_hist pls_pamp _ pis_pospk 
pis_dutyf pls_meas__ pis_period pls_rtime 
pis_edge 
| = 
pt_interp 
A Error Handling clr_err err_file set_err 
dsabl fpe rpt_count shutdown 
enabl fpe _—rpt_err validcheck 


Fig. 7-3. Waveform processing functions. 
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DISPLAY 
FUNCTIONS 


Control 
Functions 
Data and Curve 
Definition Functions 


Graph Environment 
Functions 


gr_init 
gr_dev 
gr_close 


gr_defw 
gr_defd 
gr_defa 


gr_axes 
gr_axcir 
gr_xrang 


St_yrang 


gr_title 


’ Label and Text 
—— Functions aw 
gr_xlabl 


gr_ylabl 
gr_text 


gr_txorg 


Fig. 7-4. Graphic display functions. 
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gr_clear 
gr_reset 


gr_dsply 


gr_deff 
gr_curv 
gr_mrkr 


gr_xtics 
gr_ytics 
gr_autos- 
cale 


gr_update gr_type 
gr_vwpt gr_han 
gr_pause gr owo 
gr_undef gr addmk 
gr_uncurv. gr legnd 
gr_addcv gr _Ignst 
gr_autotics gr back 
gr_frame gr _ indent 
gr_box gr_grid 
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Creation 


Memory 
Management 


Waveform 


Description Block 


Dimension Description 
Block 
Tuple Description 
Block 


Dimension Structure 


Tuple Structure 


wf_dlabel 
wf_dunits 
wf_notes 


read num 
write_num 


dim_reorder 
make_subwf 


fr array 
fr_block 
fr string 


title _ptr 
notes ptr 
wave _prev 


wave_subcnt 


wave flags 


dim_ptr 
dim_flags 


tuple_ptr 
tup_ flags 


dptr_ flags 
dptr_len 


tptr_flags 
tptr_type 


wf_title 
wf_tlabel 
wf_tunits 


mk_array 
mk_block 
mk_string 


wave_size 


wave_elsize 


wave_len 
wave_inc 


wave_type 


dim_len 
dim_inc 


tup_type 


tup_index 


dptr_next 
dptr_label 


tptr_index 
tptr_label 


tup_reorder 


zone_dim 


wave_dim 
wave_tuple 
arr_ptr 
short_arr 
long_arr 


dim_label 
dim_scale 


tup_label 
tup_scale 


dptr_scale 
dptr_units 


tptr_scale 
tptr_offset 


Fig. 7-5. Waveform manipulation utilities. 
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Waveform Generation, Acquisition, and I/O Functions 


Most SPD functions operate on a data structure called a WAVEFORM, which 
contains a data array, scaling and offset information, titles, units, and other 

6 descriptive information. The functions in this section enable you to generate 
standard waveforms such as sine or squarewaves, create SPD waveforms from 
disk files (both SPD standard format and your own formats), data arrays in C 
and QuickBASIC, or by direct acquisition from most Tektronix digitizers. You 
can also create disk files and data arrays from a SPD waveform. 


With the exception of the Signal Generation Functions, these functions create 
the waveform data structure, when called. Before using a Signal Generation 
Function, be sure to use one of the Create/Copy Waveform Utilities to create 
the data structure. 


Signal Generation Functions 


The Signal Generation functions, listed in Table 7-1, generate standard 
waveforms. Standard waveforms can be used for comparison with acquired 
waveforms, for trying out the signal processing functions with simple, predict- 
able input, or for educational purposes. These functions assume that you have 
already created the output waveform. They simply fill the waveform with data. 


Table 7-1 
SIGNAL GENERATION FUNCTIONS 
Function Purpose 
sind calculates and stores points for a single pulse of the 


function sin?(x) in a previously created waveform 


sinc calculates and stores points for sinc (sin(x)/x) in a 
previously created waveform 


sinewave generates a standard sinewave in a previously 
created waveform 


squarewave generates a Squarewave with either ramped or sine- 
squared edges in a previously created waveform 
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Create/Copy Waveform Utilities 


The Create/Copy Waveform utilities, listed in Table 7-2, let you create and copy 


waveform data structures. 
Table 7-2 © 


CREATE/COPY WAVEFORM UTILITIES 


Function Purpose 


copy_wf copies an existing waveform (including the data 
array) into a new waveform which is created the 
same size and type as the source waveform 


create wf creates a new waveform and fills the data array with 
ZeTOS 

createl wf creates a new one dimensional, one tuple waveform 
and fills the array with zeros (a special case of 
create wf) 

free _ wf releases the memory used by a waveform 

make target makes a copy of a waveform (like copy wf) but fills 
the array space with zeros instead of the source 


waveform’s array data 
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The File I/O Utilities 


The File I/O utilities, listed in Table 7-3, store and retrieve waveforms in ASCII 
or binary form. See Appendix E for a description of ADIF data formats. Note: 
file_to_wf() and afile_ to wf() are actually two names for the same function. The 
two names are included for compatibility with older versions of SPD. 


Table 7-3 
FILE I/O UTILITIES 
Function Purpose 
afile to wf reads an ADIF waveform file previously created by 


wf_to file or wf_to_afile and stores it as a waveform 


df to wf reads data from a disk file and stores it in a 
waveform data structure. By specifying the data 
type of the input file, the first value to be read and 
how many values to skip between points, almost any 
file format can be read. This function does not 
process scaling and offset data nor does it read in 
descriptive strings such as units or titles. 


file to_wf reads an ADIF waveform file previously created by 
wf_to_ file or wf_to_afile and stores it as a waveform 

wf _to_afile outputs a waveform to a file as ADIF ASCII data 

wf to file outputs a waveform to a file as ADIF binary data. 
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The Waveform Array Functions 


The Waveform Array functions, listed in Table 7-4, move data arrays to and 
from SPD waveforms. 


Table 7-4 
WAVEFORM ARRAY FUNCTIONS 
Function Purpose 
arr to wf creates a waveform from array data 
arrl to wi © creates a waveform from a one dimensional, one- 


tuple array (a special case of arr to wf) 


wf_to_array creates a contiguous array and copies waveform 


array data into it 
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The Waveform Acquisition Functions 


The Waveform Acquisition functions, listed in Table 7-5, acquire waveform data 
from most Tektronix digitizers and convert the acquired data into SPD 
waveforms. These functions are designed to give as much acquisition capability 

é& as is practical for the instrument, but do not provide a general instrument con- 
trol capability. If general control capabilities are required in your programs, 
S3FG100 GURU II, S3FG121 GPIB: Compiled BASIC language Interface, or 
S3FG122 GPIB: C Language Interface may be used in the same program as 
SPD functions. 


Table 7-5 
WAVEFORM ACQUISITION FUNCTIONS 
Function Purpose 

get11400 acquire a waveform from a Tektronix 11401, 11402, 
11801, or 11802 Digital Storage Oscilloscope 

get2220 acquire a waveform from a Tektronix 2220 or 2221 
Digital Oscilloscope 

get2230 acquire a waveform from a Tektronix 2230 Digital 
Storage Oscilloscope 

get2430 acquire a waveform from a Tektronix 2430, 2430A, 
2432, or 2440 Digital Storage Oscilloscope 

get5223 acquire a waveform from a Tektronix 5223 Digitiz- 
ing Oscilloscope 

get7854 acquire a waveform from a Tektronix 7854 


Waveform Processing Oscilloscope 


get7912 acquire a waveform from a Tektronix 7912AD or 
7912HB Programmable Transient Waveform 
Digitizer 

get7D20 acquire a waveform from a Tektronix 7D20 


Programmable Digitizer 


getRTD acquire a waveform from a Sony-Tek RTD710 Tran- 
sient Digitizer 
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Waveform Processing Functions 


The Waveform Processing functions consist of mathematical operations used in 


signal processing. These operations include: 


arithmetic functions 
frequency domain conversion 
convolution/correlation 
integration/differentiation 
data interpolation /decimation 
random number generation 
signal generation 

FIR filter generation 
Statistical measurement 

pulse parameter measurement 


point measurement 


error handling 


The Waveform Processing functions are listed in Tables 7-6 through 7-21. 
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Arithmetic Functions 


The Arithmetic functions, listed in Table 7-6, provide mathematical operations 
commonly used in signal processing. 


© Table 7-6 


ARITHMETIC FUNCTIONS 
Function Purpose 
cpx_add performs the specified complex arithmetic opera- 
cpx_sub tion on four input waveforms (each complex 
cpx_mult waveform is composed of a real and imaginary 
cpx_div waveform), producing a fifth and sixth waveform 
polar converts complex waveforms from rectangular to 
polar coordinates 
rectang converts complex waveforms from polar to rectan- 
gular coordinates 
w_add performs the specified operation on two waveforms 
w_sub producing a third waveform 
w_div 
w_mult 
w_log takes the log, exponent, power, or square root of a 
w_exp waveform, producing a second waveform 
w_power 
w_sqrt 
wc_add performs the specified operation with a double 
wc_sub precision constant on one waveform, producing a 
we_mult second waveform 
wc_div 
w_min compares corresponding elements of two waveform 
w_max arrays, or one waveform array and a constant, and 
we _min returns the minimum or maximum values in a third 
wc max waveform 
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Frequency Domain Conversion Functions 


Four Frequency Domain Conversion functions, listed in Table 7-7, convert data 
between the frequency and time domains. The taper function is normally used in 
conjunction with the Frequency Domain Conversion functions. The taper func- 
tion is a windowing function having several built-in windows to reduce leakage 
caused by sampling a non-integral number of cycles. 


Table 7-7 
FREQUENCY DOMAIN CONVERSION FUNCTIONS 
Function Purpose 
ft performs a forward FFT (Fast Fourier Transform) 


on complex time-domain data, producing complex 
frequency domain data 


ifft performs an inverse FFT on complex frequency- 
domain data, producing complex time domain data 


irfft performs an inverse FFT on frequency-domain data 
that will be purely real in the time-domain 


rfft performs a forward FFT on real time-domain data, 
producing complex frequency domain data 


taper windows a waveform with a selected windowing 
function 
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Convolution/Correlation Functions 


The Convolution/Correlation functions, listed in Table 7-8, perform convolution 
and correlation on waveforms. 


Table 7-8 
CONVOLUTION/CORRELATION FUNCTIONS 
Function Purpose 
convolve performs convolution on two waveforms and 


returns the result in a third 


fconv performs a non-circular convolution between two 
real waveforms using FFT 


fcorr performs a non-circular correlation between two 


real waveforms using FFT 


Integration /Differentiation Functions 


The Integration/Differentiation functions, listed in Table 7-9, perform integra- 
tion and differentiation on waveforms. 


Table 7-9 
INTEGRATION/DIFFERENTIATION FUNCTIONS 
Function Purpose 
integrate performs integration on a waveform and stores the 


result in a second waveform 


diff differentiates a waveform and stores the result in a 
second waveform 
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Data Interpolation and Decimation Functions 


The Interpolation/Decimation functions, listed in Table 7-10, increase or 
decrease the number of points in a waveform by a specified factor. 


Table 7-10 © 


DATA INTERPOLATION FUNCTIONS 
Function Purpose 


w_interp interpolates a uniformly sampled waveform by an 
integer factor 


w decimate decimates a waveform by an integer factor 
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Random Number Generation 


The Random Number Generation functions, listed in Table 7-11, generate ran- 
dom numbers. Associated with each random function are two functions that con- 
trol and return the status of the random function. Within SPDMENU, these 
functions are used to generate random waveforms. 


Table 7-11 
RANDOM NUMBER GENERATION FUNCTIONS 
Function Purpose 
randb returns a pseudo-random binary number (0 or 1), 


with the probability of a 1 specified by the user 


initbin initializes the binary random generator 

state b reads the current state of the binary number gener- 
ator 

randg returns a pseudo-random number of Gaussian dis- 
tribution and of specified mean and standard devia- 
tion 

initgaus initializes the Gaussian random generator 

State g reads the current state of the Gaussian number gen- 
erator 

randu returns a pseudo-random number in the interval 
[0,1] 

initunif initializes the uniform random generator 

state_u reads the current state of the uniform number gen- 
erator 
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FIR Filter Generation 


The FIR (Finite Impulse Response) Filter Generation function, listed in Table 
7-12, lets you design a linear phase FIR filter. FIR filters are commonly used 
with convolution functions to provide custom signal processing. They are also 
used with the interpolate function. 


Table 2-12 
FIR FILTER GENERATION 
Function Purpose 
eq fir calculates the coefficients for a linear phase FIR fil- 


ter 


Statistical Measurement Functions 


The Statistical Measurement functions, listed in Table 7-13, measure waveform 
parameters. 


Table 7-13 
STATISTICAL MEASUREMENT FUNCTIONS 
Function Purpose 
meanstd computes the mean, standard deviation, variance, 


and root-mean square (RMS) of a waveform. For 
the RMS value to be accurate, the waveform must 
contain an integral number of cycles. 


minmax finds the minimum and maximum parameter values 
of a waveform. The X and Y values are returned. 


sumave sums or averages the dimensions of an n-dimen- 
sional waveform, resulting in a waveform of n-1 
dimensions 
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Sinewave Parameter Measurement 


The Sinewave Parameter Measurement function, listed in Table 7-14, provides 
sinewave analysis. 


Table 7-14 
SINEWAVE PARAMETER MEASUREMENT 
Function Purpose 
sinemeas measures the parameters of the dominant 


sinewaves in a waveform. Up to the first 10 
sinewave components are found and returned in 
array. A threshold value may be specified below 


which components will be rejected. 
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Pulse Parameter Measurement Functions 


The Pulse Parameter Measurement functions, listed in Table 7-15, provide pulse 


and squarewave analysis. 


Table 7-15 


PULSE PARAMETER MEASUREMENT FUNCTIONS 


Function 


pls_amp 


pls_calc 


pls_dutyf 


pls_edge 


pls _ftime 


pls_hist 


pls_meas 


pls_negpk 


pls_pamp 


pls_period 


pls_pkfind 


pls_pospk 


pls _rtime 
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Purpose 


measures the amplitude at the center of a rectan- 
gular pulse 


calculates parameters describing a pulse from given 


values for high and low signal levels 


calculates the duty factor of a pulse 


locates the points at which the 50% transition levels 


occur on the leading and trailing edges of a pulse 


determines the falltime and falling distal, mesial, 
and proximal points for a pulse 


calculates top and bottom values for a pulse using 
the histogram method 


calculates the parameters describing a pulse be- 
tween two indices in a waveform 


determines the location and value of the negative 
pulse peak 


measures the amplitude of a periodic rectangular 
pulse at the centers between pulse transitions 


calculates the period of a pulse 
locates the peak of the first positive or negative 
going pulse (in a specified waveform period) and 


calculates the amplitude of the peak 


determines the location and value of the positive 
pulse peak 


determines the risetime and rising proximal, mesial, 


and distal points fora pulse 
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Point Measurement Functions 


Table 7-16 lists the Point Measurement functions. 


Table 7-16 
POINT MEASUREMENT FUNCTIONS 
Function Purpose 
cross finds the x value(s) at which a waveform crosses a 


given amplitude 


pt_interp computes a y value at which a uniformly sampled 


waveform crosses a given xX value 


Error Handling Functions 


Table 7-17 lists the Error Handling functions. 


Table 7-17 
ERROR HANDLING FUNCTIONS 
Function Purpose 
clr_err removes the name of the last function on the list of 


functions printed with an error message 


dsabl_fpe disables floating point exception capture 

enabl fpe enables floating point exception capture 

err file redirects error messages to a file 

rpt_count reports the occurrence of an error to the output 
device 

rpt_err reports an error message 

set_err adds the name of the function passed as a 
parameter to the end of the list of functions printed 
with errors 

shutdown cleans up after a crash error 

validcheck checks the waveform for correct format 
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Graphic Display Functions 


The Graphic Display functions let you display waveforms and associated data on 
an output device. This device can be a screen, printer, or plotter. These func- 
tions include: 


® Control Functions 
@ Data and Curve Definition Functions 
@ Graph Environment Functions 


@ Label and Text Functions 


These functions offer a selection of display capabilities, including multiple dis- 
plays, control of labels, tick marks, grids, colors, etc. 


In addition to ordinary line plots of data, two other curve plotting techniques 
are available: 


@ anti-aliased (dejagged) 


@ waveform reconstruction (interpolated) 


These two techniques may be used separately or together. The dejagged techni- 
que hides the limitations of a raster display device and presents a visually 
smooth curve. When a waveform is displayed on a raster display, some informa- 
tion can be lost and errors may occur when interpreting the display. The 
dejagged display minimizes errors of this type. (Only some devices, such as the 
IBM Professional Graphics Display, are capable of the dejagged display). 


The waveform reconstruction display overcomes the limitations of simple line 
plots. For example, a simple line plot of a sine wave having only four sample 
points per cycle will produce a display that looks nothing like a sine wave. The 
waveform reconstruction display interpolates the waveform data (it assumes the 
Nyquist criterion is met) providing a smoothed display of the underlying 
waveform. 
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Control Functions 


The Control functions, listed in Table 7-18, control graphic output. 


Table 7-18 
CONTROL FUNCTIONS 
Purpose 

gr_init initializes the graphing system 

gr_dev opens the specified graphing device 

gr_close closes the device currently open 

gr_clear clears the device currently open 

gr_dsply Outputs graph to open device 

gr_han returns the device handle of the currently open 
device (display, plotter, or printer) used by the 
other graphics routines. This function is only 
needed if you want to do custom graphics beyond 
the capabilities of the SPD waveform graphics func- 
tions. Custom graphics also requires the use of the 
Graphics Development Toolkit (GSS*CGI) avail- 
able from Graphics Software Systems, Inc. 

gr _owo reads open workstation parameters 

gr pause waits for enter key to be pressed 

gr_reset resets the current graph 

gr_size sets title, subtitle, axis label, and tick label sizes 

gr_type selects text-only mode or text and graphics mode 

gr_ update redraws graph leaving axes, title, and text un- 


t 
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defines the area of output surface to be used 
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Data and Curve Definition Functions 


The Data and Curve Definition functions, listed in Table 7-19, define data sets, 
curves, and markers from various array types. 


Table 7-19 
DATA AND CURVE DEFINITION FUNCTIONS 
Function Purpose 
gr_defw defines a data set from a waveform structure 
gr_deff defines a data set from a float data array 
gr defd defines a data set from a double data array 
pr_defa defines an automatic data set given the beginning 


and end points 


gr_curv defines a curve from two specified data sets 
gr_mrkr defines a curve displayed as markers 
gr_undef removes the specified data set from the data graph- 


ing storage area 


gr _uncurv removes a curve definition 

gr_addcv adds a curve to existing display 

gr_addmk adds a curve drawn with markers to the existing dis- 
play 

gr_legnd defines a curve legend inside the graph area 

gr_lignst defines the text string used in the legend for a 


specified curve 
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Graph Environment Functions 


The Graph Environment functions, listed in Table 7-20, set the type, color, 
range, and ticks of the x and y axes. They also include functions to set the back- 
_ ground color, draw a graph frame or box, indent the axes and display the grid. 


Table 7-20 
GRAPH ENVIRONMENT FUNCTIONS 
Function Purpose 

gr axes sets the axes type 
gr_axclr sets the axes color 
gr_xrang sets the x axis range 
gr _yrang sets the y axis range 
gr_xtics sets the tick-mark spacing on the x axis 
gr_ytics sets the tick-mark spacing on the y axis 


gr_autoscale 


resets the specified axis to automatic range 


gr_autotics sets the axis autotick mode 
gr frame draws a graph frame 

gr_box draws a graph box 

gr_back sets the background color 

gr indent sets the axes indent 

gr_ grid displays a solid or dotted grid 
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Label and Text Functions 


The Label and Text Functions, listed in Table 7-21, let you title the graph, label 
the axes, and insert text notes. 


Table 7-21 
LABEL AND TEXT FUNCTIONS 
Function Purpose 
gr title places a centered title along the top of the graph 
gr_stitl places a subtitle below the title 
gr_xlabl places a centered label under the x axis 
gr_ylabl places a label parallel to the y axis 
gr_text places a text string on the graphing display 
gr txorg sets the text origin mode 


Waveform Manipulation Utilities 


An essential element of the Tektronix Signal Processing and Display package is 
the data structure that holds waveforms and associated data. This structure al- 
lows great flexibility in the variety of ways signal data can be arranged, stored, 
and passed from one function to another. In general, this data structure is 
transparent to the user, and the details of the data organization need only be 
known to the programmer adding new functions. See Appendix B for a detailed 
description on this data structure. 


The Waveform Manipulation Utilities consist of functions and macros that ac- 
cess and manipulate the contents of the waveform data structures. (Since C lan- 
guage macros are not usable from QuickBASIC, interface functions are 
provided instead at least where they make sense.) These utilities are grouped in 
the following categories: 

String and Label Utilities 

Read/Write Element Utilities 


Subordinate Waveform Creation Utilities 


Memory Management Utilities 


Waveform Header Description Block Macros 


7-26 Signal Processing & Display 


| An Overview of the SPD Functions 


@ Dimension Description Block Macros 
@ Tuple Description Block Macros 
@ Dimension Structure Macros 


@ Tuple Structure Macros 


The Waveform Manipulation Utilities are listed in Tables 7-22 through 7-30. 


String and Label Utilities 


The String and Label utilities, listed in Table 7-22, let you associate labels, titles, 
and notes with the various components of the waveform data structure. 


Table 7-22 
STRING AND LABEL UTILITIES 
Function Purpose 
wf _dlabel assigns a label string to a waveform dimension 
wf _dunits assigns a units string to a waveform dimension 
wf notes assigns a notes string to a waveform 
wf title assigns a title string to a waveform 
wi _tlabel assigns a label string to a waveform tuple 
wf tunits assigns a units string to a waveform tuple 


Read/Write Element Utilities 


The Read/Write Element utilities, listed in Table 7-23, read and write values at 
specified waveform locations. 


Table 7-23 
READ/WRITE ELEMENT UTILITIES 
Function Purpose 
read num reads a value at a specified waveform location 
write num writes a value at a specified waveform location 
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Subordinate Waveform Creation Utilities 


The Subordinate Waveform Creation utilities, listed in Table 7-24, let you create 
and manipulate subordinate waveforms. 


Table 7-24 
SUBORDINATE WAVEFORM CREATION UTILITIES 
Function Purpose 
dim_reorder creates a subordinate waveform from a specified 


source waveform, and reorders and/or reduces the 
number of dimensions 


make_subwf makes a subordinate copy of a waveform 


iup_reorder creates a subordinate waveform, from a specified 
source waveform, and reorders and/or reduces the 
number of tuples 


zone_dim creates a subordinate waveform that accesses a sub- 
set of the elements in one of the source waveform’s 
dimensions 


Memory Management Utilities 


The Memory Management utilities, listed in Table 7-25, let you manipulate 
memory usage. 


Table 7-25 
MEMORY MANAGEMENT UTILITIES 
Function Purpose 
fr_array frees the block of memory allocated by mk_array 
fr_block frees the block of memory allocated by mk_block 
fr_string frees the string area allocated by mk_string 
mk_array allocates memory for an array 
mk_block allocates a block of memory 
mk_string allocates memory for a character string 
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Waveform Header Description Block Macros 


The Waveform Header Macros, listed in Table 7-26, provide access to waveform 
description block information. 


Table 7-26 
WAVEFORM HEADER DESCRIPTION BLOCK MACROS 
Macro Purpose 
notes ptr points to the notes string 
title ptr points to the specified waveform title string 
wave_dim returns the number of dimensions in a waveform 


wave elsize* 


returns the number of bytes in the data element 


wave flags* bit flags indicating waveform structure state (all 
flags are used internally by the waveform utilities 
for memory allocation and deallocation) 

wave _inc* returns the increment (in bytes) to the next element 
in the first dimension 

wave len returns the number of elements in the first dimen- 
sion 

wave _prev* points to the previous waveform description block 

wave _size* returns the total number of array elements as- 


wave _subcnt* 


sociated with a waveform 


returns the number of subsequent waveforms that 
point to this waveform as the previous waveform 


wave type returns the type of tuple data of the first tuple 

wave tuple returns the number of tuples in a waveform 

arr_ptr* | points to the array associated with the specified 
waveform 

short_arr* points to the element located the specified number 
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array 
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long _arr* points to the element located a specified number of 
bytes from the beginning of the long waveform array 


float_arr* points to the element located a specified number 


of bytes from the beginning of the float waveform 
array ® 


double _arr* points to the element located a specified number of 
bytes from the beginning of the double waveform 
array 


* not available through the BASIC interface 
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Dimension Description Block Macros 


The Waveform Description Block macros, listed in Table 7-27, provide access to 
waveform dimension information. 


Table 7-27 
DIMENSION DESCRIPTION BLOCK MACROS 
Macro Purpose | 
dim_ptr* returns the address of the array of W_DIM struc- 


tures for the specified waveform 


dim_flags* bit flags indicating waveform dimension state (all 
flags are used internally by the waveform utilities 
for memory allocation and deallocation) 


dim_len returns the number of elements in the specified 
dimension of a waveform array 


dim_inc* returns the increment (in bytes) to the next element 
in the specified dimension of a waveform array 


dim_label points to label string for the specified dimension of 
a waveform array 


dim_scale returns the multiplicative scale factor for the 
specified dimension of a waveform 


dim_offset returns the axis offset for the specified dimension 
of a waveform 

dim_units points to the units string for specified dimension of 
a waveform 


* not available through the BASIC interface 
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Tuple Description Block Macros 


The Tuple Description Block macros, listed in Table 7-28, provide access to 


waveform tuple information. 


Macro 


tuple ptr* 


tup_flags* 


tup_ offset 


tup_type 


tup_index* 


tup_label 


tup_scale 


tup units 


Table 7-28 


TUPLE DESCRIPTION BLOCK MACROS 


Purpose 


returns the address of the array of W_TUPLE struc- 
tures for a waveform 


bit flags indicating waveform tuple states (all flags 
are used internally by the waveform utilities for 
memory allocation and deallocation) 


returns the additive scale factor for the tuple 


returns the type of data stored for the specified 
tuple 


returns the offset (in bytes) to the specified tuple 
from the first ordered element 


points to label string for the specified tuple 


returns the multiplicative scale factor for the 
specified tuple 


points to the units string of the specified tuple 


* not available through the BASIC interface 
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Dimension Structure Macros 


The Dimension Structure Macros, listed in Table 7-29, provide access to dimen- 
sion structure information. These macros are not available through the BASIC 


interface. 
Table 7-29 
DIMENSION STRUCTURE MACROS 
Macro Purpose 

dptr flags bit flags indicating state of dimension structure 
dptr_len returns the number of elements in the dimension 
dptr_next returns the increment (in bytes) to the next element 

in the dimension 
dptr_label points to the dimension label string 
dptr_scale returns the multiplicative scale factor 


dptr_ offset 


dptr units 


returns the axis offset for the dimension 


oints to the units label strin 
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Tuple Structure Macros 


The Tuple Structure Macros, listed in Table 7-30, provide access to tuple struc- 
ture information. These macros are not available through the BASIC interface. 


Table 7-30 ® 


TUPLE STRUCTURE MACROS 
Macro Purpose 
tptr_flags bit flags indicating the status of the tuple 
tptr_type returns the type of data stored for the tuple 
tptr_index returns the offset (in bytes) to the tuple from the 


first ordered element 


tptr_label points to the label string for the tuple 
tptr_scale returns the multiplicative scale factor for the tuple 
tptr_offset returns the additive scale factor for the tuple 


tr units oints to the units label strin ® 
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Section 8 


Signal Processing 


Listed on the following pages in alphabetical order, are detailed descriptions of 
the Signal Processing and Waveform Manipulation functions. 


The description of each function in this chapter is formatted as follows: 


Name: name of function 
Purpose: tells what the function does 
Synopsis: shows the calling format for the function as 
follows: 
© function name (arguments) 


type declarations 
Description: full description of the function 


BASIC Format: describes the BASIC calling format and dif- 
ferences between type declarations. 


Example: examples are provided for many of the key 
SPD functions. Some functions require scal- 
ing of the output waveform(s) and special at- 
tention to units processing. All functions 
that require scaling or units processing have 
examples given that includes such process- 
ing. Examples of the waveform generation 
and pulse parameter functions can be found 
in Sections 5 and 6, the SPD C and 
QuickBASIC Programming tutorials. 


NOTE 


© In BASIC, parameters followed by a "%" refer to signed 16-bit in- 
tegers. Parameters followed by a "&" are 32-bit integers. 

Parameters followed by a "!" are 32-bit single precision real num- 
bers. Parameters followed by "#" are 64-bit double precision real 
numbers. Parameters followed by a "$" are strings. All arrays are 
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assumed to be zero based (the first element of the array is element 
0). 


End of Array Algorithm 
The pulse measurement functions and a few others use the eoaa parameter. 
eoaa’s arguments are described here for easy reference. 


eoaa may be given as one of the following (the C constant is followed by the 
QuickBASIC equivalent), where Arr[] is a waveform array of length N: 


EA_REPEAT or REPEAT% 


Repeat array ending value. All elements before the array start are equal in 
value to the first element Arr[0], and all elements after the array end are equal 
in value to the last element Arr[N-1], where N is the length of the array. 


EA_BOUNCE or BOUNCE% 


"Bounce" off array ends to pick replacement value. Arr{-i] is replaced with 
Arr[ +i], and Arr[N-1 +i] is replaced with Arr[N-1-i], where 0 < i < N. 


EA_INVERT or INVERT% 


"Bounce and invert.” Same as EA BOUNCE, except the sign of the selected ele- 
ment is changed. Thus, Arr[-i] is replaced with -Arr[ +i], etc. 


EA_WRAP or WRAP% 


"Wrap" around from the end back to the start and wrap around from the start to 
the end. This makes the array appear "circular", as if the array was repeated 
over and over with the data values in the same order for each repetition. In this 
case, Arr[-i] is replaced with Arr[N-i], and Arr[N-1 +i] is replaced with Arr[i-1], 
where 0 <i< =N. 


EA_ZERO or ZERO% 


An array element with a subscript that is not in the array bounds is set to zero. 
So Arr{i] = Oifi< Oori> =N. 
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NAME 
afile to wf 
PURPOSE 


Create an original waveform from the ASCII data in a file. 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
afile to wf(infile, outwave) 
char *infile; 
WAVEFORM **outwave; 
Where: 
infile: 
name of the file containing waveform data. 
outwave: 
address of pointer to the newly created original waveform. 
DESCRIPTION 


afile_to_wf creates a waveform from the data stored in the file named infile 
and puts a pointer to the new waveform in *outwave. afile_to_wf works 
with an ASCII or binary ADIF file as written by wf_to_afile or wf_to_file. 


The input file should contain a single waveform. Simple validity checks will 
be done on the file header information. If opening the input file for reading 
does not succeed, an appropriate error message is displayed. Also, any 
error in reading the file, including an unexpected end of file, is reported. 


NOTE 


This routine is identical in functionality to file_to_wf. Both func- 
tions are included for compatibility with earlier versions of SPD. 
afile_to_wf issues a FATAL under the following conditions: 

The file does not conform to the ADIF or old APD formats. 
outwave is equal to NIL. 
The input file file cannot be opened for reading. 
An error occurs in reading data from the file. 
The end of file is encountered before the complete waveform is read in. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 
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SEE ALSO 


Include files: 
wav.h 


spd.h 

Signal processing functions: 
file to wf 
wif _to_afile 


wif to file 
APPENDIX E 


The input data is not thoroughly checked for validity. If you manually edit 
or create an ASCII ADIF file for afile_to_wf, do so carefully. Binary ADIF 
files should not be edited by the user. 


BASIC FORMAT 


Call bafiletowf(inS, out%,statusZ) 


Where: 
‘in$ 
name of file containing waveform data 
out$ 


integer identifying the newly created waveform 
status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
EXAMPLE 
Rees 


#include “tekspd.h”" 
ERRORTYPE status; 
WAVEFORM *wave 


status = afile to _wf("mywave.wav" , &wave) 


BASIC: 

" SINCLUDE: '\tek\spd\include\tekspd.bi' 

outz =1 

call bafiletowf("mywave.wav",out%,status2Z) @ 
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NAME 
arrl to wf 


PURPOSE 
Creates and fills an original waveform structure from the description of a 
one dimensional array, and then associates the array with the waveform. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
arrl_to_wf (arrayptr, dimlen, tuptype, wave) 


BYTE *arrayptr; 
index dimlen, tuptype; 
WAVEFORM **wave; 


Where: 


arrayptr: 
pointer to the source array. 


dimlen: 
number of elements in the array. 


tuptype: 
data type of the array elements. Known types are W_ SHORT, 
W_LONG, W_FLOAT, and W_ DOUBLE. 


wave: 
address of the pointer to the waveform to be created. 
DESCRIPTION 


arrl_to_wf allocates memory space for an original waveform structure and 
its associated substructures according to the description of the one dimen- 


sional source array and then associates the array with the waveform. It 
returns the address of the new waveform in wave. 


It assumes that the array is contiguous and that arraypir points to the first 
element of the array. 


The fields in the WAVEFORM structure are filled as follows: 
The pointer to the previous waveform is set to NIL. 
The number of subordinate waveforms is set to zero. 
The pointer to the title is set to NIL. 
The pointer to the notes area is set to NIL. 


The bit flags are set to show that the structure space, but not the array 
space, was allocated by one of the waveform utilities and can, therefore, 
be released by them. (Since the array space is not known to have been 
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allocated by one of the waveform utilities, the appropriate bit flag to 
allow the waveform utilities to release the array space will not be set.) 


The array size is set to dimlen. 


The data element size is calculated as the size of the data type as 
specified by tuptype. 

The array pointer is set to arrayptr. 

The number of dimensions is set to one. 


The pointer to the substructures containing dimension information 
points to the W_DIM structure of the first (only) dimension. 


The number of tuples is set to one. 


The pointer to the substructures containing the tuple information 
points to the W_TUPLE structure of the first (only) tuple. 


The fields in the W_DIM structure is filled as follows: 
The bit flags are set to zero. 
The dimension length is set to dimlen. 
The increment to the next element is set to the size of the data type. 
The pointer to the label is set to NIL. 
The multiplication scale factor is set to 1.0. 
The axis offset is set to zero. 
The pointer to the units is set to NIL. 
The fields in the W_TUPLE structures are filled as follows: 
The bit flags are set to zero. 
The tuple data type is set to tuptype. 
The byte offset from the first tuple is set to zero. 
The pointer to the label is set to NIL. 
The multiplication scale factor is set to 1.0. 
The additive scale factor offset is set to zero. 
The pointer to the units is set to NIL. 
arrl_to_wf issues a FATAL error if: 
dimlen is < 0. 
tuptype is undefined (see wav.h). 
There is not enough free memory available for the structures. 
If a FATAL error occurs, *wave is set to NIL. 
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SEE ALSO 
Include files: 


wav.h 
spd.h 


Signal processing function: 


arr to wi 
BASIC FORMAT 


CALL barrltowf(arrayptr#(0),dimlen&, tuptypeZ ,waveZ, statusZ) 
Where: 


arrayptr# (0): 
first element of the source array. The type of the array must cor- 
respond to the type specified by tuptype%. 


dimlen&: 
number of elements in the array. 


tuptype%: 


data type of the array elements. Use the pre-defined constant 
WSHORT%, WLONG%, WFLOAT%, or WOOUBLE%. 


wave%: 


integer identifying the waveform to be created. 
status [o:: 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
Cc: 


#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM *wave 
double myarray([(1024); 
Fill array with data here. 
status = arrl_to_wf((BYTE *)myarray, (long)1024, W_FLOAT, &wave) ; 


BASIC: 


' SINCLUDE: '\tek\spd\include\tekspd.bi' 
DIM myarray#(1024]) 
outzZ =1 
Fill array with data here. 
call barrltowf (myarray#(0),1024&,WDOUBLEZ, outZ, status2) 
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NAME: 


arr_to_ wf 


PURPOSE 


Creates and fills an original waveform structure from the description of an 
array, and associates the array with the waveform. 


SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 
arr_to_wf (arrayptr, ndims, dimarr, ntups, tuparr, wave) 


BYTE *arrayptr; 

int ndims, ntups, tuparr[]; 
long dimarr[]; 

WAVEFORM **wave; 


Where: 


arrayptr. 
pointer to the source array. 
ndims: 
number of dimensions in source array. 


dimarr. 
address of an array containing the length of each dimension, where the 
length of the 0th dimension is in dimarr[0], and so on. (Dimensions are 
numbered from zero.) 

ntups: 
number of tuples in the data element of the source array. 

tuparr: 
address of an array containing the types of each tuple, where the type of 
the Oth tuple is in tzparr[0], and so on. (Tuples are numbered from 


zero.) Known types are W SHORT, W_LONG, W_FLOAT, and 
W_DOUBLE. 


wave: 
address of the pointer to the waveform to be created. 


DESCRIPTION 
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arr_to_wf allocates memory space for an original waveform structure and its 
associated substructures according to the description of the source array 
and then associates the array with the waveform. It returns the address of 
the new waveform in wave. 


It assumes that the array is contiguous and that arrayptr points to the first 
tuple of the first element of the array. Furthermore, if the array has more 
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than one dimension, it assumes that the elements in the last dimension are 
adjacent and that the elements in the first dimension are the farthest apart. 
More precisely, it assumes that the distance between elements (in bytes) for 
the last dimension is the data element size. Then working backwards, the 
distance between elements for each dimension, n, is the distance for dimen- 
sion n+1 times the length of dimension n+1. As an example, the offset (in 
bytes) from the array pointer for element{x, y, z] of a three dimensional 
array is assumed to be: 


x * distance for the first dimension + 
y * distance for the second dimension + 
z * distance for the last dimension. 
The fields in the WAVEFORM structure are filled as follows: 
The pointer to the previous waveform is set to NIL. 
The number of subordinate waveforms is set to zero. 
The pointer to the title is set to NIL. 
The pointer to the notes area is set to NIL. 


The bit flags are set to show that the structure space, but not the array 
space, was allocated by one of the waveform utilities and can, therefore, 
be released by them. (Since the array space is not known to have been 
allocated by one of the waveform utilities, the appropriate bit flag to 
allow the waveform utilities to release the array space is not set.) 


The array size is calculated as the product of the dimension lengths in 
dimarr[]. 

The data element size is calculated as the sum of the byte lengths of the 
data types in tuparr[]. 

The array pointer is set to arrayptr. 

The number of dimensions is set to ndims. 


The pointer to the substructures containing dimension information 
points to the W_DIM structure of the first dimension. 


The number of tuples is set to ntups. 


The pointer to the substructures containing the tuple information 
points to the W_TUPLE structure of the first tuple. 


The fields in the W_DIM structures are filled as follows: 
The bit flags are set to zero. 
The dimension length is set to the corresponding number from dimarr[/). 


@ The increment to the next element is calculated such that the increment 
for the last dimension is the data element size; and then working back- 
wards, the increment for each dimension, n, is the increment for dimen- 
sion n+1 times the length of dimension n+ 1. 
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The pointer to the label is set to NIL. 
The multiplication scale factor is set to 1.0. 
The axis offset is set to zero. 
The pointer to the units is set to NIL. 
The fields in the W_TUPLE structures are filled as follows: 
The bit flags are set to zero. 
The tuple data type is set to the corresponding type from tuparr[]. 


The byte offset from the first tuple is calculated such that the offset for 
the first tuple is zero; and then working forwards, the offset for each 
tuple, n, is the offset for tuple n-1 plus the ie length of the data type 
of tuple n-1 


The pointer to the label is set to NIL. 
The multiplication scale factor is set to 1.0. 
The additive scale factor offset is set to zero. 
The pointer to the units is set to NIL. 
arr to_wf issues a FATAL error if: 
ndims < = 0 orndims > MAXDIMS (currently set to 10; see wav.h). 
ntups < = 0 orntups > MAXTUPS (currently set to 256; see wav.h). 
Any of the dimension lengths in dimarr[] is < 0. 
Any of the tuple types in tuparr[] is undefined (see wav.h). 
There is not enough free memory available for the structures. 
If a FATAL error occurs, *wave is set to NIL. 


SEE ALSO 
Include files: 


wav.h 


spd.h 
BASIC FORMAT 


CALL barrtowf(arrayptr#(0),ndims%,dimarr&(0),ntups%,tuptypeZ, 
waved, statusZ) 


Where: 


arrayptr# (0) 
first element of the source array. The type of the array must cor- 
respond to the type specified by tuptype%. 


ndims% 
number of dimensions in source array. 
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dimarr&(0) 
array containing the length of each dimension. 


ntups To 
number of tuples in the data element of the source array. 


tuptype Yo 
The type of the tuples. Use the pre-defined constant WSHORT%, 


WLONG%, WFLOAT%, or WOOUBLE%. 


wave Yo 
integer identifying the waveform to be created. 


status Zo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME: 


clr_err 
PURPOSE | @ 
Reports any floating point exception errors, pops the name of the currently 


executing function off the function name stack and returns the worst known 
error. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
clr_err (error) 


ERRORTYPE error; 


Where: 


error. 
Known worst case error from the calling function (NOERROR, 
WARN, FATAL or CRASH). 


DESCRIPTION 
If there are any floating point exception errors that have not been reported, 
they are reported via a call to spt_count. The name of the currently execut- 
ing function is popped off the function name stack. 


clr err returns the error code error if no floating point errors have occurred. 
If such errors have occurred, the error code returned is the worst error of 
WARN and error. 


clr_err is typically the last function called before a function that has called 
set_err returns. 
SEE ALSO 
Include files: 
spd.h 
Signal processing library functions: 


rpt_count 
rpt_err 


Set_ err @ 
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BASIC FORMAT 


CALL bclrerr(error%,status2Z) 


@ error 


integer indicating known worst case error from the calling function. 

Should be one of NOERROR%, WARN%, FATAL%, or CRASH%. 
status % 

integer indicating the execution status of the function. Result will be 

one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME: 


convolve 


PURPOSE © 


Performs convolution on two waveforms and returns the result in a third 
waveform. 


SYNOPSIS 
#include "tekspd.h" 
ERRORTYPE convolve(h, x, skiplen, sym, eoaa, y) 


WAVEFORM *h, *x; 
long skiplen; 
int sym, eoaa; 
WAVEFORM *y; 


Where: 
h: 
pointer to the transfer waveform function. 


x 


pointer to the input waveform. @ 
y: 


pointer to the output waveform. 


skiplen: 
number of elements to skip before storing the results in the output 
waveform. 


sym: 
type of symmetry involved: NOSYM, EVENSYM, or ODDSYM. 
eoaa: 

end-of-array algorithm to use for end effects: EA REPEAT, 

EA BOUNCE, EA INVERT, EA_WRAP or EA_ZERO. 


DESCRIPTION 
Convolution is performed on the two waveforms, h and x, using the follow- 
ing formulas: 
barrin]: m=O, 1, 2, «--, = 1 
KR urcinj: m= 6, 1, 2, «ee, B* 1 


al 
y_arr(n] = h_arr{k] x_arr[(n-k] © 
=0 


forn = 0,1,2,..., N+M-2 
where 
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h_arr, x_arr, andy _arr are waveform arrays 
N and M are the lengths of A_arr and x arr, respectively. 


The array elements that have subscripts that are out of bounds are 
@ found using eoaa. If the output waveform array has a length greater 

than N + M - 1, nothing is done with the elements past this length. On 
the other hand, if the output waveform array has a length shorter than 
N + M -1, it is simply filled up to its shorter length. The length and 
type information of each waveform is taken only from the first dimen- 
sion and the first tuple. Also, the convolution is performed only on the 
data in the first dimension and the first tuple. 


skiplen specifies the number of elements to skip before filling the out- 
put waveform. Thus, the first skiplen elements will be unused after con- 
volution, and only the following elements will be placed in the output 
array. The output array, however, will begin at arr(0], as usual. 

sym is used to indicate the symmetry involved. It can be either NOSYM 
for no symmetry, EVENSYM for even symmetry, or ODDSYM for odd 
symmetry. Even symmetry means that h[n] = h[N-1-n]. Odd symmetry 
means that h[n] = -h[N-1-n]. For N odd, n = 0, 1,2,..., (N-3) /2. 
For N even, n = 0,1,2,...,N /2. 

See page 8-2 for details on the use of the eoaa parameter. 


convolve returns a WARNING error and uses the default value of 
EA_ REPEAT if eoaa is not one of the defined values. 


It returns a FATAL error and the convolution is not performed if any of 
the following conditions are not met: 


h, x, and y must be valid waveforms. 


skiplen must be greater than or equal to zero and be less than or 
equal to M + N - 2. 


sym must be NOSYM, EVENSYM, or ODDSYM. 


Memory must be available for the creation of two temporary double 
arrays, one of length N and the other approximately the length of y + 
N. 


The function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 


SEE ALSO 
Include files: 


wav.h 


@ spd.h 
sp.h 
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BASIC FORMAT 


CALL bconvolve( hZ, x%, skiplen&, symZ, eoaaZ, y%, statusZ ) 
Where: @ 
h% 

integer identifying the transfer waveform function. 


x% 
integer identifying the input waveform. 


skiplen& 
number of elements to skip before storing the results in the output 
waveform. 


sym 
type of symmetry involved. Should be one of the pre-defined constants 
NOSYM%, EVENSYM%, ODDSYM%. 


eoaa% 
end-of-array algorithm to use for end effects. Should be one of the pre- 
defined constants REPEAT%, BOUNCE%, INVERT%, WRAP%, or 
ZERO%. See page 8-2 for details about the meaning of these constants. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. r 


EXAMPLE 
Cc 


#include "tekspd.h" 
ERRORTYPE status; 

WAVEFORM *inl, *in2, *out 
char outunits[80]; 


status = convolve(inl, in2, (long)0, NOSYM, EA_REPEAT, &out); 


strcpy(outunits,tup_units(inl1,0)); /* V units from inl */ 
strcat(outunits,” * "); 
strcat(outunits,tup_units(in2,0)); /* V units from in2 */ 


status = wf_tunits(outunits ,COPY,0,out); /* insert new units */ 
Status = wf_dunits(dim_units(in1,0), COPY,0,out); 


dim_scale(out,0) = dim_scale(inl1,0); 


BASIC: 
" SINCLUDE: ‘\tek\spd\include\tekspd.bi' & 
inlZ% = 1: in2% = 2: out% =3 


call beonvolve(in1l%, in2%, 0&, NOSYMZ, REPEAT%, out%, statusZ) 


¢ 


set units and scaling for waveform outZ 
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brtupunits(in12Z,0,inlunits$,inllenZ,status2Z) 
brtupunits(in22%,0,in2units$,in2lenZ,statusZ) 


bwftunits(inlunitsSt+" * "+in2unitsS,0%,out%,statusZ) 


@ brdimunits(in1%,0,inHunitsS, inHlen%, status2Z) 
bwfdunits("inHunitsS,0%,outZ,statusZ) 


brdimscale(inlZ%,0,hsf#,status2Z) 
bwdimscale(outZ,0,hsf#,status2Z) 
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NAME 
copy wf 


PURPOSE 


Create an original waveform that is a copy of another waveform, including 
the array data. 


SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 
copy_wf(inwave, outwave) 


WAVEFORM *inwave; 
WAVEFORM **outwave; 


Where: 


inwave: 


pointer to the waveform to be copied 


outwave: 


address of the pointer to the new waveform to be created 


DESCRIPTION 


8-18 


copy _wf allocates memory space for a new waveform structure and its as- 
sociated substructures and array. It returns the address of the new 
waveform in outwave. 


The new waveform is an original waveform and the array of the new 
waveform is contiguous. The new waveform array is filled with data copied 
from the source waveform array. 


The information in the new WAVEFORM structure is copied from the 
source except: 


The pointer to the previous waveform is set to NIL. 
The number of subordinate waveforms is set to zero. 


The title pointer is set to a copy of the title string (if any). It is set to 
NIL if the source waveform does not have a title. 


The notes pointer is set to a copy of the notes string (if any). It is set to 
NIL if the source waveform does not have a notes string. 


The bit flags are set to show that the structure space, array space and 
any title or note strings were allocated by one of the waveform utilities 
and can, therefore, be released by them. 


The array pointer points to the first tuple of the first element of the new 
waveform array. 
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The pointer to the substructures containing dimension information 
points to the W_DIM structure for the first dimension of the new 
waveform. 


The pointer to the substructures containing the tuple information 
points to the W_TUPLE structure for the first tuple of the new 
waveform. 


The information in the W_DIM structures of the new waveform is copied 
from the source except: 


The bit flags are set to show that any label or units string were copied 
by one of the waveform utilities and can therefore be released by them. 
If both the label and units strings were NIL then the bit flags are set to 
zero. 


The increment to the next element is calculated such that the increment 
for the last dimension is the data element size; and then working back- 
wards, the increment for each dimension, n, is the increment for dimen- 
sion n+1 times the length of dimension n+1. 


The label pointer is set to a copy of the label string (if any). It is set to 
NIL if the source waveform does not have a label string for the cor- 
responding dimension. 


The units pointer is set to a copy of the units string (if any). It is set to 
NIL if the source waveform does not have a units string for the cor- 
responding dimension. 


The information in the W_TUPLE structures of the new waveform is 
copied from the source except: 


The bit flags are set to show that any label or units string were copied 
by one of the waveform utilities and can therefore be released by them. 
If both the label and units strings were NIL then the bit flags are set to 
zero. 


The byte offset from the first tuple is calculated such that the offset for 
the first tuple is zero; and then working forwards, the offset for each 
tuple, n, is the offset for tuple n-1 plus the byte length of the data type 
of tuple n-1. 

The label pointer is set to a copy of the label string if any. It is set to 
NIL if the source waveform does not have a label string for the cor- 
responding tuple. 


The units pointer is set to a copy of the units string (if any). It is set to 
NIL if the source waveform does not have a units string for the cor- 


¢ responding tuple. 
copy _wf issues a FATAL error if: 
inwave is not a valid waveform. 


There is not enough free memory available for the new waveform struc- 
tures. 
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There is not enough free memory available for the new array. 
If a FATAL error occurs, *outwave is set to NIL. 


SEE ALSO 


= © 


wav.h 


NOTES 


If subwave points to the address of wave upon function entry, it is then the 
user’s responsibility to note the waveform structure previously associated 
with wave. 


BASIC FORMAT 


CALL bcopywf(inwaveZ, outwaveZ, status) 


Where: 


inwave Jo 
integer identifying the waveform to be copied. 


outwave Yo 
integer identifying the new waveform to be created. 


status To 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
ie 
#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM *wave, *newwave; 
status = copy _wf(wave, &newwave); 


BASIC: 


" SINCLUDE: ‘\tek\spd\include\tekspd.bi' 
DIM myarray#[1024) 


wavez =1: newwavez% = 2 
call bcopywf(wave% ,newwave%, statusZ ) 
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NAME 
cpx_add 


PURPOSE 


Performs complex addition on corresponding elements of four n-dimen- 
sional input waveform arrays and places the sums in two n-dimensioinal out- 
put waveform arrays. 


SYNOPSIS 
#include “tekspd.h" 


ERRORTY PE 
cpx_add(rel,iml,re2,im2, rout, iout) 


WAVEFORM *rel, (iml,*re2,*im2,*rout, *iout; 


Where: 


rel: 
pointer to one real input waveform. 
wm: 
pointer to one imaginary input waveform. 
re2: 
pointer to the other real input waveform. 
im2: 
pointer to the other imaginary input waveform. 
rout: 


pointer to the output waveform that will hold the real components of 
the sums of the elements. 


lout: 
pointer to the output waveform that will hold the imaginary com- 
ponents of the sums of the elements. 


DESCRIPTION 
Complex addition is performed on an element by element basis in which 
values in the output waveform arrays are computed in the following manner: 


rout=reltre2 

iout=imlt+im2 
The least number of dimensions and the least number of elements in any 
given dimension of rel, im, re2, im2, rout, or iout are used as the basis for 
determining the extent to which rout and iout are "filled" with complex sums. 


Each "element" is actually an ordered n-tuple. Function cpx_add only uses 
the first tuple of each n-tuple in rel, im], re2, and im2 to create the sum 
that is stored in the first tuple of the corresponding elements in rout and 
lout. 
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All waveforms must be valid, but the data type of the first tuple of each 
waveform do not need to be the same. cpx_add performs the complex addi- 
tion in double precision and coerces the results into the types of the rout 
and iout waveform arrays. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 


spd.h 
wav.h 


BASIC FORMAT 
CALL bepxadd(re1%,im1Z%,re2%,im2%, rout%, iout2, status2Z ) 


Where: 


rel% 

integer identifying one real input waveform. 
iml% 

integer identifying one imaginary input waveform. 
re27 

integer identifying the other real input waveform. 
im2% 

integer identifying the other imaginary input waveform. 
routZo 


integer identifying the output waveform that will hold the real com- 
ponents of the sums of the elements. 


tlout% 


integer identifying the output waveform that will hold the imaginary 
components of the sums of the elements. 


status Zo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
EXAMPLE 
C: 
#include "tekspd.h" 


ERRORTYPE status; 
WAVEFORM *rel, *iml, *re2, *im2, *rout, *iout; 


Status = cpx_add(rel, iml, re2, im2, &rout, &iout); 


status = wf_tunits(tup_units(rel,0),COPY,0,rout); /* copy units */ 
status = wf_dunits(dim_units(re1,0),COPY,0, rout); 


8-22 Signal Processing & Display 


Signal Processing 
cpx_add 


status = wf _tunits(tup_units(re1,0),COPY,0,iout); 
status = wf_dunits(dim_units(rel,0),COPY,0,iout); 


dim_scale(rout,0) = dim_scale(rel1,0); 
G dim_scale(iout,0) = dim_scale(rel,0); 
BASIC: 
' SINCLUDE: ‘\tek\spd\include\tekspd.bi’ 
relZ = 1: imlZ% = 2 


re2Z = 3: im2Z% = 4 
routz = 5: ioutZ = 6 


call bepxadd(relZ, im1%, re2%, im2%, rout%, iout%Z, statusZ) 


* set units and scaling for waveform outZ 
brtupunits(re1%,0,inVunitsS, inVlenZ,status2Z) 
bwftunits(inVunitsS, 02%, rout%, status2Z) 
bwftunits(inVunitsS,0%,iout%,statusZ) 


brdimunits(re1Z,0,inHunitsS, inHlenZ,statusZ) 
bwfdunits(inHunitsS,0%,rout%, statusZ) 
bwfdunits(inHunitsS,0%,ioutZ,statusZ) 


brdimscale(re1Z,0,hsf#,statusZ) 
bwdimscale(routzZ ,0,hsf#, statusZ) 


bwdimscale(ioutZ,0,hsf#,statusZ) 
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NAME 


cpx_div 
PURPOSE 6 


Performs complex division on corresponding elements of four n-dimen- 
sional input waveform arrays and places the quotients in two n-dimensional 
output waveform arrays. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
cpx_div(rel,iml,re2,im2,rout,iout) 


WAVEFORM *rel,iml,*re2,*im2, *rout, *iout; 


Where: 


rel: 
pointer to one real input waveform. 
im: 
pointer to one imaginary input waveform. @ 


re2: 
pointer to the other real input waveform. 


im2: 
pointer to the other imaginary input waveform. 


rout: 
pointer to the output waveform that will hold the real components of 
the quotients of the elements. 


lout: 
pointer to the output waveform that will hold the imaginary com- 
ponents of the quotients of the elements. 


DESCRIPTION 


Complex division is performed on an element by element basis in which 
values in the output waveform arrays are computed in the following manner: 


rout = feloregtimi-im2 
re2* +im2 


ent im iml+ re2—rel*im2 ® 
a wean | 


re2° +im2 


The least number of dimensions and the least number of elements in any 
given dimension of rel, im1, re2, im2, rout, or iout are used as the basis for 
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determining the extent to which rout and iout are "filled" with complex 
quotients. 


Each "element" is actually an ordered n-tuple. Function cpx_div only uses 
the first tuple of each n-tuple in rel, im, re2, and im2 to create the 
quotient that is stored in the first tuple of the corresponding elements in 
rout and jout. 


All waveforms must be valid, but the data type of the first tuple of each 
waveform do not need to be the same. cpx_div performs the complex 
division in double precision and coerces the results into the types of the 
rout and iout waveform arrays. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 


spd.h 
wav.h 


BASIC FORMAT 


CALL bepxdiv(relZ,im1%,re2Z,im2Z, rout%, iout%, statusZ) 


6 Where: 


rel% 
integer identifying one real input waveform. 
im1% 
integer identifying one imaginary input waveform. 
re2% 
integer identifying the other real input waveform. 
im2% 
integer identifying the other imaginary input waveform. 
rout% 
integer identifying the output waveform that will hold the real com- 
ponents of the quotients of the elements. 
lout% 
integer identifying the output waveform that will hold the imaginary 
components of the quotients of the elements. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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EXAMPLE 
i 


#include "tekspd.h" 

ERRORTYPE status; 

WAVEFORM *rel, *iml, *re2, *im2, *rout, *iout; 
char outunits([(80]; 


status = cpx_div(rel, iml, re2, im2, &rout, &iout); 


strepy(outunits,tup_units(rel,0)) 
streat(outunits,"” / ") 
strcat(outunits,tup_units(re2,0)) 


status = wf_tunits(outunits,COPY,0,rout); /* copy units */ 
status = wf_dunits(dim_units(rel,0),COPY,0,rout); 

status = wf_tunits(outunits ,COPY,0,iout); 

status = wf _dunits(dim_units(re1,0),COPY,0,iout); 


dim_scale(rout,0) = dim_scale(rel,0); 


dim scale(iout,0) = dim_scale(rel1,0); 


BASIC: 


' SINCLUDE: ‘\tek\spd\include\tekspd.bi’ 
relz = 1: im1Z = 2 

re2z% = 3: im2z% = 4 

routz = 5: ioutzZ = 6 


call bepxdiv(relZ, im1Z%, re2%, im2%, rout%, ioutZ%, status2Z) 


" set units and scaling for waveform outz 
brtupunits(re1Z,0,inlunits$,inllen%Z,status2Z) 
brtupunits(re2Z,0,in2unitsS$,in2lenZ,statusZ) 
VunitsS = inlunitsS+" / "+in2units 
bwftunits(VunitsS,0%, rout%, status2Z) 
bwftunits (VunitsS ,0Z,ioutZ, statusZ) 


brdimunits(re1Z%,0,inHunitsS, inHlenZ,status2Z) 
bwfdunits(inHunitsS,0%,rout%, status2Z) 
bwfdunits(inHunitsS,02Z,iout%,status2Z) 


brdimscale(rel% ,0,hsf#,status2Z) 
bwdimscale(routzZ,0,hsf#,statusZ) 


bwdimscale(iout2Z,0,hsf#,statusZ) 
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NAME 
cpx_mult 


PURPOSE 


Performs complex multiplication on corresponding elements of four n- 
dimensional input waveform arrays and places the products in two n-dimen- 
sional output waveform arrays. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
cpx_mult(rel,iml,re2,im2, rout, iout) 


WAVEFORM *rel,iml,*re2,*im2,*rout, *iout; 


Where: 


rel: 
pointer to one real input waveform. 
im: 
pointer to one imaginary input waveform. 
re2: 
pointer to the other real input waveform. 
im2: 
pointer to the other imaginary input waveform. 
rout: 


pointer to the output waveform that will hold the real components of 
the products of the elements. 


lout: 
pointer to the output waveform that will hold the imaginary com- 
ponents of the products of the elements. 


DESCRIPTION 
Complex multiplication is performed on an element by element basis in 
which values in the output waveform arrays are computed in the following 
manner: 


rout = rel * re2 - iml * im2 
iout = iml * re2 + rel * im2 


The least number of dimensions and the least number of elements in any 
given dimension of rel, inl, re2, im2, rout, or iout are used as the basis for 
determining the extent to which rout and iout are "filled" with complex 
products. 
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Each “element” is actually an ordered n-tuple. Function cpx_mult only uses 

the first tuple of each n-tuple in rel, im 1, re2, and im2 to create the product 

that is stored in the first tuple of the corresponding elements in rout and 

lout. © 
All waveforms must be valid, but the data type of the first tuple of each 

waveform do not need to be the same. cpx_mult performs the complex mul- 

tiplication in double precision and coerces the results into the types of the 

rout and iout waveform arrays. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 
spd.h 
wav.h 
BASIC FORMAT 


CALL bepxmult(re1Z,im1%,re2%, im2%, routZ, iout%, statusZ) 


Where: 


rel% © 
integer identifying one real input waveform. 

iml% 
integer identifying one imaginary input waveform. 

re2% 
integer identifying the other real input waveform. 


im2% 
integer identifying the other imaginary input waveform. 


routYo 
integer identifying the output waveform that will hold the real com- 
ponents of the products of the elements. 


iout% 


integer identifying the output waveform that will hold the imaginary 
components of the products of the elements. 


status To 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. @ 
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EXAMPLE 
Ce 


#include "tekspd.h”" 

ERRORTYPE status; 

WAVEFORM *rel, *iml, *re2, *im2, *rout, *iout; 
char outunits [80]; 


status = cpx_mult(rel, iml, re2, im2, &rout, &iout); 


strepy(outunits,tup_units(rel1,0)) 
strcat(outunits,” * ") 
strcat(outunits,tup_units(re2,0)) 


status = wf _tunits(outunits,COPY,0,rout); /* copy units */ 
status = wf_dunits(dim_units(rel,0),COPY,0,rout); 

status = wf_tunits(outunits,COPY,0,iout); 

status = wf_dunits(dim_units(rel1,0),COPY,0,iout); 


dim_scale(rout,0) = dim_scale(rel,0); 


dim_scale(iout,0) = dim_scale(rel,0); 


BASIC: 


’ SINCLUDE: ‘\tek\spd\include\tekspd.bi’ 
relZ = 1: im1Z = 2 

re2zZ = 3: im2Z% = 4 

routZ = 5: ioutZ = 6 


call bepxmult(relZ, im1%, re2Z%, im2Z, rout%, iout%Z, statusZ) 


* set units and scaling for waveform outZ 
brtupunits(re1Z,0,inlunitsS,inllen%, status2Z) 
brtupunits(re2Z,0,in2unitsS,in2len%,status2Z) 
VunitsS$ = inlunitsS+" * "“+in2units 
bwftunits(VunitsS ,0%, routZ%, status2Z) 
bwftunits (VunitsS,0%,ioutZ,statusZ) 


brdimunits(re1Z,0,inHunitsS, inHlenZ,statusZ) 
bwfdunits(inHunits$,02%, routZ,statusZ) 
bwfdunits(inHunitsS,0%,ioutZ, statusZ) 


brdimscale(rel1Z%,0,hsf#, status2Z) 
bwdimscale(routZ ,0,hsf#,statusZ) 


bwdimscale(ioutZ,0,hsf#,statusZ) 
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NAME 
cpx_sub 


PURPOSE 


Performs complex subtraction on corresponding elements of four n-dimen- 
sional input waveform arrays and places the differences in two n-dimen- 
sional output waveform arrays. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
cpx_sub(rel,iml,re2,im2, rout, iout) 


WAVEFORM *rel,iml,*re2,*im2,*rout, *iout; 


Where: 


rel: 
pointer to one real input waveform. 
im: 
pointer to one imaginary input waveform. 
re2: 
pointer to the other real input waveform. 
im2: 
pointer to the other imaginary input waveform. 
rout: 
pointer to the output waveform that will hold the real components of 
the differences of the elements. 
lout: 


pointer to the output waveform that will hold the imaginary com- 
ponents of the differences of the elements. 


DESCRIPTION 


Complex subtraction is performed on an element by element basis in which 
values in the output waveform arrays are computed in the following manner: 


rout = rel - re2 
iout = iml - im2 


The least number of dimensions and the least number of elements in any 
given dimension of rel, im, re2, im2, rout, or iout are used as the basis for 
determining the extent to which rout and iout are "filled" with complex dif- 
ferences. 


Each "element" is actually an ordered n-tuple. Function cpx_sub only uses 
the first tuple of each n-tuple in rel, im, re2, and im2 to create the dif- 
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ference that is stored in the first tuple of the corresponding elements in rout 
and jout . 


All waveforms must be valid, but the data type of the first tuple of each 
waveform do not need to be the same. cpx_sub performs the complex sub- 
traction in double precision and coerces the results into the types of the 
rout and tout waveform arrays. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 
SEE ALSO 
Include files: 
spd.h 
wav.h 


BASIC FORMAT 


CALL bepxsub(re1Z,im1Z,re2%,im2%, routZ, ioutZ, status2Z) 


Where: 


rel% 
integer identifying one real input waveform. 


iml% 

integer identifying one imaginary input waveform. 
re27o 

integer identifying the other real input waveform. 


1m2% 
integer identifying the other imaginary input waveform. 


rout% 
integer identifying the output waveform that will hold the real com- 
ponents of the differences of the elements. 


loutYo 
integer identifying the output waveform that will hold the imaginary 
components of the differences of the elements. 


status [% 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
#include "“tekspd.h”" 
ERRORTYPE status; 
WAVEFORM *rel, *iml, *re2, *im2, *rout, *iout; 


status = cpx_sub(rel, iml, re2, im2, &rout, &iout); 
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status = wf_tunits(tup_units(rel,0),COPY,0,rout); /* copy units */ 


status = wf_dunits(dim_units(re1,0),COPY,0, rout); 
status = wf_tunits(tup_units(rel,0),COPY,0,iout) ; 
status = wf_dunits(dim_units(re1,0),COPY,0,iout); 


dim_scale(rout,0) = dim_scale(rel,0); 
dim_scale(iout,0) = dim_scale(rel,0); 
BASIC: 

’ SINCLUDE: '\tek\spd\include\tekspd.bi' 
relz = 1: imlZ = 2 


re2zZ = 3: im2Z = 4 
routz = 5: ioutz = 6 


call bepxsub(relZ, im1Z%, re2%, im2Z, routZ, ioutZ, status2Z) 


* set units and scaling for waveform outZ 
brtupunits(rel%,0,inVunitsS,inVlenZ, status2Z) 
bwftunits(inVunitsS,0%,routZ, status2Z) 
bwftunits (inVunitsS ,0%,iout%, status2Z) 


brdimunits(re1Z,0,inHunitsS, inHlen%Z,status2Z) 
bwfdunits(inHunits$,0%,rout%, statusZ) 
bwfdunits(inHunitsS,0%,iout%, statusZ) 


brdimscale(rel1%,0,hsf#, statusZ) 
bwdimscale(rout% ,0,hsf#, statusZ) 


bwdimscale(ioutZ,0,hsf#,statusZ) 
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NAME 
createl wf 


PURPOSE 


Create and fill an original waveform structure and array for a single dimen- 
sional, single tuple waveform. 


SYNOPSIS 


ERRORTYPE 
createl wf(length, tuptype, wave) 


index length; 
int tuptype; 
WAVEFORM **wave; 


Where: 
length: 
number of elements in the waveform 


tuptype: 
the type of data that will be stored. Known types are W_SHORT, 


W_LONG, W_FLOAT, and W_DOUBLE. 
wave: 
address of the pointer to the waveform to be created. 
DESCRIPTION 


Create] _wf allocates memory space for an original waveform structure and 
its associated substructures and array. It returns the address of the new 
waveform in wave. The array is zero filled. 


The fields in the WAVEFORM structure are filled as follows: 
The pointer to the previous waveform is set to NIL. 
The number of subordinate waveforms is set to zero. 
The pointer to the title is set to NIL. 
The pointer to the notes area is set to NIL. 


The bit flags are set to show that the structure space and the array 
space were allocated by one of the waveform utilities and can, there- 
fore, be released by them. 


The array size is calculated as the dimension length in length. 
The data element size is calculated as the byte length of the data type in 
tuptype. 


The array pointer points to the first (only) tuple of the first element of 
the waveform array. 


The number of dimensions is set to 1. 


2 
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The pointer to the substructures containing dimension information 
points to the structure of the first (only) dimension. 


The number of tuples is set to 1. 
The pointer to the substructures containing the tuple information © 
points to the structure of the first (only) tuple. 
The fields in the structure are filled as follows: 
The bit flags are set to zero. 
The dimension length is set to length. 
The increment to the next element is set to the size of the tuple type. 
The pointer to the label is set to NIL. 
The multiplication scale factor is set to 1.0. 
The axis offset is set to zero. 
The pointer to the units is set to NIL. 
The fields in the W_TUPLE structure is filled as follows: 
The bit flags are set to zero. 
The tuple data type is set to the corresponding type from tuptype. 
The byte offset from the first tuple is set to 0. 
The pointer to the label is set to NIL. @ 
The multiplication scale factor is set to 1.0. 
The additive scale factor is set to zero. 
The pointer to the units is set to NIL. 
Createl_wf issues a FATAL error if: 
The tuple type in tuptype is undefined (see wav.h). 
There is not enough free memory available for the structures. 
There is not enough free memory available for the array. 
If a FATAL error occurs, *wave is set to NIL. 


SEE ALSO 
Include files: 


spd.h 
wav.h 


Signal processing function: 


create wf © 


BASIC FORMAT 


CALL bcreatelwf( length&, tuptypeZ%, wave%, status% ) 
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Where: 


length& 
number of elements in the waveform. 


tuptype To 
the type of data that will be stored. Use the pre-defined constant 


WSHORT%, WLONG%, WFLOAT%, or WOOUBLE%. 


wave Jo 
integer identifying the waveform to be created. 


status [% 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
Be 
#include "“tekspd.h" 
ERRORTYPE status; 


WAVEFORM *wave 
status = createl_wf((long)1024, W_FLOAT, &wave); 


BASIC: 


’ SINCLUDE: '\tek\spd\include\tekspd.bi’ 
outz =1 
call bcreatewf(1024&,WDOUBLEZ, out%, statusZ) 
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NAME 


create wf 


PURPOSE 


Create and fill an original waveform structure and array. 


SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 
create wf (ndims, ‘dimarr, ntups, tuparr, wave) 


int ndims, ntups, tuparr[]; 
long dimarr[(]; 
WAVEFORM **wave; 


Where: 


ndims: 
number of desired waveform array dimensions. 


dimarr. 
address of an array containing the length of each dimension, where the 
length of the Oth dimension is in dimarr[0], and so on. (Dimensions are 
numbered from zero.) 


ntups: 
number of desired tuples in the data element. 

tuparr: 
address of an array containing the types of each tuple, where the type of 
the Oth tuple is in tuparr{0], and so on. (Tuples are numbered from 
zero.) Known types are W SHORT, W_LONG, W_FLOAT, and 
W_DOUBLE. | 


wave: 
address of the pointer to the waveform to be created. 


DESCRIPTION 
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create_wf allocates memory space for an original waveform structure and its 
associated substructures and array. It returns the address of the new 
waveform in wave. The array is zero filled. 


The fields in the WAVEFORM structure are filled as follows: 
The pointer to the previous waveform is set to NIL. 
The number of subordinate waveforms is set to zero. 
The pointer to the title is set to NIL. 
The pointer to the notes area is set to NIL. 
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The bit flags are set to show that the structure space and the array 
space were allocated by one of the waveform utilities and can, there- 
fore, be released by them. 


The array size is calculated as the product of the dimension lengths in 
dimarr[]. 


The data element size is calculated as the sum of the byte lengths of the 
data types in tuparr[]. 


The array pointer points to the first tuple of the first element of the 
waveform array. 


The number of dimensions is set to ndims. 


The pointer to the substructures containing dimension information 
points to the W_DIM structure of the first dimension. 


The number of tuples is set to mtups. 


The pointer to the substructures containing the tuple information 
points to the W_TUPLE structure of the first tuple. 


The fields in the W_DIM structures are filled as follows: 
The bit flags are set to zero. 
The dimension length is set to the corresponding number from dimarr[]. 


The increment to the next element is calculated such that the increment 
for the last dimension is the data element size; and then working back- 
wards, the increment for each dimension, n, is the increment for dimen- 
sion n+1 times the length of dimension n+ 1. 


The pointer to the label is set to NIL. 


The multiplication scale factor is set to 1.0. 
The axis offset is set to zero. 
The pointer to the units is set to NIL. 
The fields in the W_TUPLE structures are filled as follows: 
The bit flags are set to zero. 
The tuple data type is set to the corresponding type from tuparr{[]. 


The byte offset from the first tuple is calculated such that the offset for 
the first tuple is zero; and then working forwards, the offset for each 
tuple, n, is the offset for tuple n-1 plus the byte length of the data type 
of tuple n-1. 


The pointer to the label is set to NIL. 
The multiplication scale factor is set to 1.0. 


The additive scale factor is set to zero. 
The pointer to the units is set to NIL. 
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create_wf issues a FATAL error if: 
ndims < = 0 or ndims > MAXDIMS (currently set to 10; see wav.h). 
ntups < = 0 orntups > MAXTUPS (currently set to 256; see wav.h). 
Any of the dimension lengths in dimarr[] is < 0. ® 
Any of the tuple types in tuparr[] is undefined (see wav.h). 
There is not enough free memory available for the structures. 
There is not enough free memory available for the array. 
If a FATAL error occurs, *wave is set to NIL. 


SEE ALSO 
Include files: 


spd.h 
wav.h 


BASIC FORMAT 


CALL bcreatewf(ndims%, dimarr&(0), ntups%, tuparrz(0), wavez, 
statusZ ) 


Where: 


ndims% 

number of desired waveform array dimensions. © 
dimarr&(0) 

array containing the length of each dimension, where the length of the 

Oth dimension is in dimarr&(0), and so on. (Dimensions are numbered 

from zero.) 


ntups% 
number of desired tuples in the data element. 

tuparr7(0) 
array containing the types of each tuple, where the type of the Oth tuple 
is in tuparr7o(0), and so on. (Tuples are numbered from zero.) Use 
the pre-defined constant WSHORT%, WLONG%, WFLOAT%, or 
WDOUBLEZ%. 


wave Yo 
integer identifying the waveform to be created. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. eo 
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CrOSs 
PURPOSE 
Finds a specified number of level crossings of a waveform. 
SYNOPSIS 
#include "tekspd.h" 
ERRORTYPE 
cross(input, start, dir, level, n_cross, n, eoaa, arr) 
WAVEFORM *input; 
long start; 
int dir, n_cross, n, eoaa; 
double level, arr[]; 
Where: 
input: 
pointer to the waveform. 
Start: 
long integer waveform index at which the search for crossings is to 
begin. 
dir: 
direction in which to search, beginning from start. It should be either 
RIGHT or LEFT. 
level: 


level at which waveform crossings are to be detected. 


nN _Cross: 
number of /evel crossings to be located. It should be at least 1. 


minimum number of waveform samples that must stay crossed (either 
all above or all below /evel, after a /evel crossing is found, in order to 
declare that crossing to be valid. This parameter aids in noise rejection, 
and should be at least 1. 


€oaa: 
end-of-array algorithm to use, if necessary. Accepted values are 
EA REPEAT, EA BOUNCE, EA INVERT, EA_WRAP, and 
EA_ZERO. 


arr: 
user-supplied double array in which the level crossings found are passed 
back from cross. The length of arr should be at least n_cross. Valid 
crossings are stored in arr in the order that they are found beginning 
from start. If fewer than n_cross valid crossings are found, the remain- 
ing elements of arr are set to -1.0. 
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DESCRIPTION 


cross operates only on the first dimension and first tuple of the input 
waveform. cross does not consider tangency of the waveform to the 
specified level to be a crossing. A crossing is defined to occur only if the 
waveform actually crosses level. 


Once a crossing is detected, cross does further processing to check if the 
crossing 1s a valid one with respect to . If nm waveform samples beyond the 
detected crossing do not change sign with respect to /evel, then the detected 
crossing is valid. Else, it is not, and the search for a crossing continues. 


If a valid crossing occurs at an integer index, no further processing is neces- 
sary. If the valid crossing occurs at a non-integer index, then cross finds the 
fractional part of the crossing by the following method : 


1) Twelve waveform samples (6 each on either side of the crossing) 
are used after subtracting the value of level from them to fit a 12th 
order Lagrange polynomial. 


2) The fractional part of the crossing is given by the root of the 

Lagrange polynomial, which is bracketed between two integer 

waveform indices. To estimate this root, an iterative method is used. 

The estimated root is considered to be sufficiently accurate if the 

value of the Lagrange polynomial differs from zero by no more than 

1.e-10, at the estimated root. The iterations are terminated when this © 
tolerance is achieved. If convergence is poor, and the above 

tolerance is not attained within 25 iterations, then the iterations are 
terminated. In this case, the value of the root after the 25th iteration 

is taken to be the fractional value of the crossing. 


cross searches for crossings only within waveform array bounds. If cross 
finds crossings at waveform array extremities, then it uses an end-of-array 
algorithm specified by eoaa to complete its calculations. Since a 12th order 
Lagrange polynomial is used in cross, end-of-array effects may be present in 
crossings found within 6 waveform indices of either end of the array. 


See page 8-2 for details on the use of the eoaa parameter. 


cross issues a FATAL error if input is NIL or if temporary memory is not 
available to cross to complete its calculations. 


A number of default actions are taken by cross if any of the parameters, 
start, dir, n_cross, n, Of eoaa, are invalid values. In such cases, cross issues a 
WARNing error message pertaining to the action taken. Specifically, if: 


start 
is less than or equal to 0, then start is set to 0, and dir is set to 6 
RIGHT. If start is greater than or equal to the maximum waveform 
index, then start is set to the maximum index, and dir is set to LEFT. 
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dir 
is not either of the keywords LEFT or RIGHT, then it is set to 
RIGHT. 


n_Cross 
is less than or equal to 0, then it is set to 1. 


is less than or equal to 0, then it is set to 1. 


eoaa 
is not a defined flag word, then it is set to EA REPEAT. 

The function returns an error code (as defined in the include file spd.h) in- 

dicating whether or not it was able to execute correctly. 


SEE ALSO 
Include files: 
spd.h 
wav.h 


sp.h 
BASIC FORMAT 


CALL bcross( inputZ, start&, dirZ, level#, ncrossZ, nZ, eoaaiz, 
arr#(0), statusZ ) 


Where: 
inputT% 
integer identifying the waveform. 
start& 
long integer waveform index at which the search for the crossings is to 
begin. 
dir% 
direction in which to search, beginning from start. 


0 for left 
1 for right. 


level # 
level at which waveform crossings.are to be detected. 


nerossTo | 
number of level crossings to be located. It should be at least 1. 


n@Zo 
minimum number of waveform samples that must stay crossed (either 
all above or all below level), after a level crossing is found, in order to 
declare that crossing to be valid. This parameter aids in noise rejection, 
and should be at least 1. 
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eoaa% 
end-of-array algorithm to use. Should be one of the pre-defined con- 
stants REPEAT%, BOUNCE%, INVERT%, WRAP%, or ZERO%. See 
page 8-2 for details about the meaning of these constants. 

arr# (0) 
user-supplied double array in which the level crossings found are passed 
back from cross. The length of arr should be at least n_ cross. Valid 
crossings are stored in arr in the order that they are found beginning 
from start. If fewer than n_cross valid crossings are found, the remain- 
ing elements of arr are set to -1.0. 


status %o 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
df to wf 
PURPOSE 


Reads data from a file into a memory array, creates an original waveform 
structure and associates the array with the waveform. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
df_to_wf(fname,ab,inType,outType,soOften, first,wave) 


char *fname; 

BOOL ab; 

int inType,outType,soOften, first; 
WAVEFORM **wave; 


DESCRIPTION 


fname: 
pointer to the filename. 

ab: 
flag designating how the file data was written: 0 means ASCII data, 1 
means binary data. 

inType: 
indicates how binary input data is stored. Known types are: W SHORT, 
W_LONG, W_FLOAT, and W_DOUBLE. 


outType: 
indicates how output data is stored in the waveform. Known types are: 
W_SHORT, W_LONG, W_FLOAT, and W_DOUBLE. 


soOften: 
every soOftenth data value is used. For example, every data item is used 
if soOften is 1; every other value is used if soOften is 2, etc. 

first: 
use data item number first as the first legitimate item, 1.e., discard the 
first - 1 items. 


wave: 
address of the pointer to the waveform to be created. 
Df_to_wf produces a single tuple, single dimension waveform from data on 


a disk file. Binary files are assumed to contain pure data of the type 
specified. 


ASCII data files may contain filler (non-numeric) characters; the function 
uses whatever looks like a number. An ASCII number may be preceded by 
an optional sign (+ or -), followed by an optional decimal point (.), fol- 
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lowed by one or more digits (a decimal point may be embedded if there was 

not a leading decimal point). The digits (or a trailing decimal point) may be 

followed by the letters e or E and a numeric exponent (one or more digits). 

The exponent may be preceded by an optional sign (+ or -). 

Df _to_wf uses arr] to_wf. The resultant waveform is as produced by that @ 
function except that the array space is marked as releasable. 


SEE ALSO 
arrl_to_wf(3spd) 
arr _to_wf(3spd) 


BASIC FORMAT 


CALL bdftowf( fnameS, ab%, inType%Z, out Type% , so- 
OftenZ, firstZ ,waveZ,status2Z) 


Where: 


fname$ 
file name 


ab% 
flag designating how the data was written where: 


0 for ASCII data, 
1 for binary data, and © 
-1 for IBM BASIC binary float or double data. 
inTypeQ% 
data type of binary input data. Use the pre-defined constant 
WSHORT%, WLONG%, WFLOAT%, or WDOUBLE%. 
outType% 
data type to be used in the SPD waveform. Known types are as for in- 
Type. 
soOften 
every soOftenth value will be used. 


first 


discard the first first - 1 data times. | 


wave%: 
integer identifying the waveform to be created. 


status%o: 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. & 
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EXAMPLE 
C: 


#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM *wave 


status = df_to_wf("myfile.wav",0, W_FLOAT, 2, 1, &wave); 
BASIC: 


' SINCLUDE: ‘'\tek\spd\include\tekspd.bi’ 
wavez =1 


call bdftowf("myfile.wav", 0 ,WDOUBLEZ ,2 ,1, wave%, status2Z) 


Signal Processing & Display 8-45 


Signal Processing 
diff 


NAME 
diff 
PURPOSE 
Differentiates a waveform. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
diff(in,N, eoaa, out) 


WAVEFORM *in, *out; 
int N; 
int eoaa: 
Where: 
in: 
pointer to the waveform containing data to be differentiated. 


oul: 
pointer to the waveform containing data after differentiation. 


N: 
length of the differentiator impulse response. 
eoaa: 
end-of-array-algorithm to use for end effect while differentiating. 
DESCRIPTION 


diff approximates the differential of the waveform pointed to by in and 
stores the result in the waveform pointed to by out according to the follow- 
ing algorithm: 
First, the impulse response is created: 
h{n]: O0<n<N 
where N is an input parameter, the length of the impulse response. 
1) N even, N24: K = N/2 


_ K4 
binek} =— 9 {SH 2 m-sin = e+} for -K<n<K-l 


2) N odd, N=5: K = (N-1)/2 


K 
h(n+k] = x m-sin (27mn for -K<n<K 


2 
(K + IN + 1) mm N+1 


Next, the differentiated output is generated by the linear convolution of h 
and in. M = the length of the input waveform array. The output differen- 
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tiated waveform is provided for0<n<M - 1, after compensating for the in- 
trinsic delay of K samples. Any elements beyond M - 1 are set to zero. 


N is the impulse response length of the Finite Impulse Response differen- 
tiator to be used. The accuracy of the differentiation depends on N. If N is 
even, the output is delayed by one half sample interval. The output is not 
delayed if an odd N is chosen. N = 2 andN = 3 work best with waveforms 
that are fairly oversampled. Their error increases monotonically as the fre- 
quency of the input increases. N greater than 3 works better with high fre- 
quencies. If N is odd, the error becomes very significant at frequencies 
exceeding 


tr(N-1) 
N+ 
The table below lists some of the expected errors when differentiating a 
sine wave of varying frequencies and varying values of N. The errors in the 
table were taken as the maximum absolute error over the entire output 
waveform values are computed as follows: 


in{i] = sin(freq*t*i) fori = 0,1,2,..., length of in- 1 


Sine Function Differentiation Errors 


freq (=) 

N_ 0.01 0.10 0.30 0.51 0.70 0.90 

2 1.29e-06 1.27e-03 3.41e-02 1.66e-01 4.12e-01 8.42e-01 
3. 5.15e-06  5.14e-03 1.33e-01 6.02e-01 139e+00 2.52e+00 
5 1.09e-02 1.02e-01 1.77e-01 1.38e-02 2.59e-01 2.28e-01 
8 5.88e-03 4.50e-02 3.04e-02 8.07e-03 5.16e-02 1.49e-01 
9 7.54e-03 4.98e-02 6.06e-02 9.51e-02 2.09e-01 1.16e- +00 
16 2.92e-03 7.14e-03 1.28e-02 4.27e-03 2.37¢e-02 3.25¢e-02 
17 4.10e-03  4.80e-03 1.54e-02 2.96e-02 5.67e-02 1.44e-01 
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Eoaa is used to find a point outside of the array bounds in the convolve 
function called from diff. Eoaa values are detailed on page 8-2. 


Both waveforms must be valid. If the two waveforms are the same, the dif- 
ferentiated result overwrites the input. If the waveform arrays are not the 
same size, the output waveform array is valid only to the length of the 
shorter array. If the output waveform is longer than the input waveform, 
the invalid elements are zero-filled. 
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Data is taken from the first dimension of the input waveform and is placed 

in the first dimension of the output waveform. Data type information is 

taken from the first tuple of both the input and output waveform arrays. 

The impulse response length, N, must be at least 2. The sampling interval © 
of time, the distance between consecutive points along the x-axis, is ex- 

pected to be one. If this is not the case, the results must be scaled by the 

proper amount. To scale the results, divide each output waveform array ele- 

ment by the distance between the successive data points along the x-axis. 


The function returns an error code (as defined in the include file spd.h) in- 
dicating whether or not it was able to execute correctly. 


SEE ALSO 
Signal processing library function: 
convolve 
Include files: 
wav.h 


spd.h 
sp.h 


BASIC FORMAT 


CALL bdiff(in%,N%, eoaa%, outZ, statusZ) @ 


Where: 
ino 
integer identifying the waveform containing data to be differentiated. 


N% 
length of the differentiator impulse response. 


eoaaYo 
end-of-array algorithm. Should be one of the pre-defined constants 
REPEAT%, BOUNCE%, INVERT%, WRAP%, or ZERO%. See page 8- 
2 for details about the meaning of these constants. 


outZ% 
integer identifying the waveform containing data after differentiation. 
status 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
c 6 


#include "tekspd.h" 
ERRORTYPE status; 

WAVEFORM *wavein, “waveout; 
char outunuts [80]; 
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status = diff(wavein, 3, EA_REPEAT, waveout); 
strcepy(outunits,tup_units(wavein,0)); /* V units from wavein */ 


strcat(outunits,” / “): 
strcat(outunits,dim_units(wavein,0)); /* V units from wavein */ 


status = wf_tunits(outunits,COPY,0,waveout); /* insert units */ 
status = wf_dunits(dim_units(wavein,0), COPY,0,waveout) ; 


dim_scale(out,0) = dim_scale(in,0); 
status = wc_div(waveout, dim_scale(wavein, 0)); 


BASIC: 


' SINCLUDE: '\tek\spd\include\tekspd.bi' 
DIM myarray#[(1024]) 
in% = 1: outZ =2 


call bdiff(in%, 3, REPEATZ, outZ,status2Z) 


' set vertical units for waveform outZ 
brtupunits(inZ,0,inVunits$,inVlenZ,status2Z) 
brdimunits(inz,0,inHunitsS,inHlenZ,status2Z) 
bwftunits(inVunitsS+" / "tinHunitsS,0Z,outZ,statusZ) 


‘ copy horizontal units to waveform outZ 
brdimunits(inz,0,inHunitsS, inHlenZ,statusZ) 
bwfdunits("inHunitsS,0%, outZ%,status%Z) 


' copy horizontal scale to waveform outz 
brdimscale(inz,0,hsf#, status2Z) 
bwdimscale(outZ%,0,hsf#,statusZ) 


' divide out% by input horizontal scale factor 
bwediv(out%, hsf#, status2Z) 
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NAME 
dim_reorder 


PURPOSE 
Changes the order and number of dimensions in a waveform array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
dim reorder (wave, ndims, order, del_keep, subwave) 


WAVEFORM *wave; 
int ndims, order[{], del_keep; 
WAVEFORM **subwave; 


Where: 


wave: 
pointer to the source waveform. 


ndims: 
new number of dimensions in waveform array. 


order. 
address of an array containing the new order of the dimensions in terms 
of the current dimension numbers. (Dimensions are numbered from 
zero.) 


del_keep: 
flagword used to indicate whether the source waveform should be 
deleted if possible; defined values are DELETE or KEEP. 


subwave: 
address of the pointer to the subordinate waveform to be created. 


DESCRIPTION 


dim_reorder allocates memory space for a subordinate waveform structure 
and its associated substructures. It returns the address of the new subor- 
dinated waveform in subwave. 


The new waveform is similar to the source except that the number of dimen- 
sions may be fewer and the order of the dimensions may be different. When 
forming the new waveform, this function copies the information about the 
specified dimensions of the source waveform in the specified order, and cal- 
culates a new array size. It does not change the order or number of the 
tuples. 


dim_reorder does not delete or rearrange any array data, but the unused 
dimensions are not accessible from the new subordinate waveform. 
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However, by using copy _wf() on the resultant waveform, a new waveform 
with compacted and rearranged array data can be created. 


dim_reorder may also attempt to delete the source waveform, wave, depend- 
ing on the value of de/_keep and whether wave is an original waveform or 
not. 


If del_keep is DELETE and wave is not an original waveform, subwave is 
made subordinate to the previous waveform of wave, the subordinate 
counter of the previous waveform of wave is incremented, and an attempt is 
made to delete wave. If not, subwave is made a subordinate of wave and the 
subordinate counter of wave is incremented. 


String fields (titles, notes, dimension labels, dimension units, tuple labels 
and tuple units) for sebwave are LINKed to the string information in wave. 
That is, the pointer to the string in wave is copied to subwave, but the cor- 
responding bit in the bit flags field is reset indicating that no memory was 
allocated for subwave to contain the string. When space has been allocated 
for a String in wave and wave is to be DELETE, the appropriate bit flag is 
set in subwave so that the strings will be properly maintained. 


The information in the new WAVEFORM structure is copied from the 
source except: 


The pointer to the previous waveform is set to either wave or the pre- 
vious waveform of wave as explained above. 


The number of subordinate waveforms is set to zero. 


The bit flags are set to show that the structure space was allocated by 
one of the waveform utilities and can, therefore, be released by them. 
The setting of the bit flags for string fields (title and notes) is explained 
above. 


The array size is calculated as the product of the lengths of the new 
number of dimensions. 
The number of dimensions is set to ndims. 
The pointer to the substructures containing dimension information 
points to the W_DIM structure for the first dimension of the new 
waveform. 
The pointer to the substructures containing the tuple information 
points to the W_TUPLE structure for the first tuple of the new 
waveform. 
The information in the ndims W_DIM structures of the source is copied to 
the new waveform in the order specified by order[] except the bit flags for 
the label and units strings. These are described above. 


The information in the W_TUPLE structures of the new waveform is 
copied from the source without changing the order or number of 
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W_TUPLEs except the bit flags for the label and units strings. These are 
described above. 


dim_reorder issues a FATAL error if: 
wave iS not a valid waveform. 
ndims < 1 or ndims > the number of dimensions in wave. 


Any of the dimension numbers in order[] are < 0 or > = the number of 
dimensions in wave. 


Any dimension number appears more than once in order[]. 

There is not enough free memory available for the new structures. 
dim_reorder issues a WARNing error if: 

del_keep is not KEEP or DELETE; KEEP is assumed. 


wave is a subordinate waveform and del_keep is DELETE, but wave can- 
not be deleted (i.e., the bit flags do not indicate that the structure space 
was allocated by one of the waveform utilities or the subordinate 
waveform counter is not zero). 


If a FATAL error occurs, *subwave is set to NIL. 


SEE ALSO 


Include files: ) 
spd.h 


wav.h 
Signal processing functions: 
tup_reorder 
copy_wf 
NOTES 


If subwave points to the address of wave upon function entry, it is then the 
user’s responsibility to note the waveform structure previously associated 
with wave. 


BASIC FORMAT 


CALL bdimreorder( waveZ, ndimsZ, order%(0), delkeepZ, subwave7Z, 
statusZ ) 


Where: 


wave Jo 
integer indicating the source waveform. _ 


ndims% 
new number of dimensions in waveform array. 
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orderZo(0) 
array containing the new order of the dimensions in terms of the cur- 
rent dimension numbers. (Dimensions are numbered from zero.) 


delkeep% 
flagword used to indicate whether the source waveform should be 
deleted if possible. 


0 for keep 
1 for delete 


subwave % 
integer identifying the subordinate waveform to be created. 


status Zo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
dsabl_fpe 


PURPOSE © 
Disables floating point exception capture. 


SYNOPSIS 
dsabl_fpe() 


DESCRIPTION 


dsabl fpe disables floating-point exception capture. Any floating point ex- 
ceptions that occur when floating point exception capture is disabled will be 
corrected to the best ability of the hardware, but the user will not be in- 
formed. 


SEE ALSO 
Signal processing library function: 
enabl_fpe 


BASIC FORMAT 


CALL bdsablfpe () © 
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NAME 
enabl_fpe 


PURPOSE 

Enables floating-point exception capture. 
SYNOPSIS 

#include "tekspd.h" 


enabl_fpe(ON) 


Where: 


ON: 
keyword for floating-point exception capture (see include file spd.h). 


DESCRIPTION 


enabl_fpe enables floating-point exception capture so that the user can 
know if any floating point exceptions occurred during the execution of SPD 
functions. 


SEE ALSO 
Include file: 
spd.h 
Signal processing library function: 
dsabl_fpe 
BASIC FORMAT 


CALL benablfpe( onZ ) 


Where: 


on% 
keyword for floating-point exception capture (see include file spd.h). 
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NAME 
eq _fir 


PURPOSE 
Computes the coefficients for a Linear Phase FIR Filter. 


SYNOPSIS 


#include "tekspd.h" 
#include “eq fir.h" 


ERRORTYPE 
eq fir(fspec,fullh,h,ext,dev) 


FSPEC *spec; 

BOOL fullh; 
WAVEFORM *h, *ext; 
double *dev; 


Where: 


fspec: 
pointer to the data structure containing design specifications for the fil- 
ter. 


fullh: 
Boolean flag to determine if all or half of the impulse coefficients are to 
be output. 


h: 
pointer to the waveform where the impulse response is to be stored. 
ext: 
pointer to the waveform where the extremal frequencies are to be 
stored. 


dev: 
pointer to double variable to store the peak deviation from the ideal fre- 
quency response. 


DESCRIPTION 


eq_fir uses the Remez exchange algorithm to design linear phase FIR digi- 
tal filters. These filters have a minimum weighted Chebyshev error in the 
approximation to a desired frequency response. As it stands, this program is 
capable of designing the more common filter types such as low pass, 
bandpass, highpass, multi-band, Hilbert transform filters and differen- 
tiators. Other filters can be designed by modifying the two functions 
eq_fmag and eq_fweight located in the file eq_fuser.c. 


The specification for the filter is contained in data structure fspec. The 
definition of fspec is shown here and contained in the file eq_fir.h. 
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#define MAXBANDS 10 /*max number of bands in filter*/ 
/* 

*Filter type to be designed 

*/ 

6} #define PASSSTOPO 

#define PASSSTOPO 
#define DIFF 1 
#define HILBERT 2 
#define FUSER 3 
/* 

*Filter hand structure definition 

*/ 


struct fband { 
double blower; /*frequency of lower edge of band*/ 
double bupper; /*frequency of upper edge of band*/ 
double bmag; /*band mag (1, 0) or slope if DIFF*/ 
double bwght; /*weighting for band*/ 

fi 

typedef struct fband FBAND; 


/* 

*Filter specification definition 

ms 

struct fspec { 
short flen; /*length of filter */ 
short ftype; /*filter type */ 
short . nbands; /*number of bands in filter */ 
FBAND band{MAXBANDS]; /*filter band definitions */ 


}; 
typedef struct fpec FSPEC; 


The structure fspec has four entries in it. Each entry describes a different 
characteristic of the filter. 


flen: 
describes the number of elements in the filter. The minimum length for 
a filter is 2, The maximum length is dependent on the available memory 
and the amount of time one is willing to wait for the program to design 
the filter. Filter lengths of 70 or less can be designed rather quickly 
whereas filters with lengths of 100 or more can take considerable execu- 
tion time. 


Stype: 
the type of filter to be designed. The type should be set to one of 


PASSSTOP, DIFF, HILBERT, or FUSER. PASSSTOP will cause the 
design program to design lowpass, bandpass, highpass, bandstop, or mul- 
tiband filters. The actual type of filter is determined by the band 
specifications. PASSSTOP filters are characterized by having impulse 
responses which are positive symmetrical (i.e., h(n) = h(-n)). 
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FUSER is like PASSSTOP except that the user written portions of 
eq_fmag and eq_fweight are called to determine the desired magnitude. 
and weighting characteristics. 


DIFF designs a filter that differentiates a signal when convolved with it. 

HILBERT transforms and DIFFerentiators are characterized by having 

impulse responses which are negative symmetrical (i.e., h(n) = -h(n)). 
nbands: 

defines the number of distinct bands in the filter. This value must be in 

the range of 1 to MAXBANDS. This value describes the number of ele- 

ments used in the band structure for specifying the filter. 


band: 
contains an array of data structures used to describe the filter bands. 
One element of this structure is used for each band that is specified. 
The components of this data structure specify the lower and upper 
edges of the frequency band, the desired magnitude in the band and a 
weighting factor for the band. 


The band edges are specified as fractions of the sampling frequency. 
Since non-aliased signals can only approach 1/2 the sampling rate, the 
range of values for edge specifications must be between 0 and 0.5 in- 
clusive. Adjacent bands should have a transition area between them. 
This transition region may be arbitrarily small, but the smaller it gets 
the greater the deviation of the desired magnitude in the final filter. 
Bands are also not allowed to overlap each other and must be in ascend- 
ing order (low frequency to high). 


blower: 
specifies the lower edge of a band. 


bupper. 
specifies the upper edge of a band. 


bmag: 
specifies the desired magnitude of the band. A value of 0 indicates a 
stop band where a value of 1 indicates a pass band. If other values are 
entered here, they imply the gain of the band (i.e., 0.5 means to pass the 
frequencies at half amplitude). 


This value is interpreted to mean the desired slope, if a differentiator is 
being designed. 


bwght: 
specifies the weighting function for the band. The higher this number, 
the smaller the resulting deviation from the desired magnitude will be. 


The Boolean flag fullh describes the amount of data that will be written to 
h. If fullh is TRUE then the entire impulse response coefficients will be writ- 
ten to A. If fullh is FALSE then only the unique terms of the impulse 
response are written out. For a filter of length N, the following information 
is generated. 
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h{0] through h[(N + 1)/2] where N is odd 
h{0] through h{N/2] where N is even 


Ext is a waveform where the extremal frequencies are to be written. Ex- 
tremal frequencies are those frequencies where the maximum deviation 
from the desired response are to be found. The required length of this 
waveform for a filter length of N is determined as follows: 


(N +3)/2 for PASSSTOP with odd N 

N/2+1 for PASSSTOP with even N 
(N+1)/2 for DIFF or HILBERT with odd N 
N/2+1 for DIFF or HILBERT with even N 


Dev is the variable which contains the maximum deviation coefficient from 
the desired response of the filter. The peak deviation occurs at the extremal 
frequencies and can be computed by determining the band where the ex- 
tremal frequency occurs and multiplying the weight of that band by the 
deviation. 


The range of amplitudes for a given band of frequencies is determined by 
the relationship: 


bmag - dev/wght < magnitude < bmag + dev/wght 


Throughout a frequency band, the errors in magnitude will alternate be- 
tween positive and negative values. 


Eq_fir will only write on the first dimension and the first tuple of the output 
waveforms, A and ext. If h or ext are NIL then no output will be generated 
for that parameter. 


A FATAL error is issued under the following conditions: 


fspec does not contain valid data. Valid data consists of having one of 
the four filter types specified for type, a filter length value that is greater 
than or equal to 2, the number of bands is in the range of 1 to MAX- 
BANDS, and each band specification must be in the range of 0 to 0.5 
with the upper band edge being greater than the lower band edge and 
no bands that overlap each other. 

A and ext are not valid waveforms or NIL. If they are valid waveforms 
they must be of sufficient length to contain all the desired information 
to be output. 


There is not sufficient free memory for a temporary working space. 
A WARNing error is issued under the following conditions: 


If a program does not converge to a solution. This should only hap- 

pen if machine roundoff errors become significant. Most likely the 
resulting filter will have adequate performance since these errors are 
not likely to occur until the final iterations of the design. 


Any floating point errors that occur during execution. 
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eq _fir returns an error code (as defined in the spd.h include file) indicating 
whether or not it was able to perform correctly. 


The following example illustrates the use of this function to design a 7-ele- 
ment lowpass filter. The passband is defined to extend from 0 to 0.2 of the 
sampling frequency. The stopband extends from 0.3 to 0.5 of the sampling 
rate. The desired error in the stopband is to be 1/10 the error in the 
passband. From this information, the fspec data structure is set up as: 


ftype = PASSSTOP 

flen =7 

nbands =2 

band[0].blower = 0 
band[0].bupper =0.2 
band[0].bmag =1 
band[0].bwght =1 
band[1].blower = 03 
band[1].bupper = 0.5 
band{1].bmag = 0 
bqand[1].bwght = 10 


For this filter, ext must contain 5 elements for the extremal frequency data 
and A must contain flen or 7 elements for output of the full impulse 
response. Eq _fir is called with the following arguments: 


eq_fir(fspec,TRUE,h, ext, &dev) ; 


The following information is returned in the waveforms A, ext and the vari- 
able dev. 


h{0] = -0.0162525620 = h{6] 
h[1] = 0.12413393 = h[5] 
h[2] = 0.36754611 = h{4] 
h[3] = 0.49913760 = hf3] 


ext[0}] = 0.0078125 

ext{1] = 0.2 

ext([2] = 0.3 

ext[3] = 0.3625 

ext[4] = 0.5 

dev = 0.44825625 
The actual frequency response in the passband will be 1.0 + 0.44825625 
(weighting factor = 1). In the stopband the deviation will be + 0.044825625 
(weighting factor = 10). It is also worth noting that two of the extremal fre- 


quencies, ext/1] and ext{2], occur at the edges of the pass and stop bands. 
At ext{1] the frequency amplitude will be 1.0 - dev and at ext/2] the 
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amplitude will be +dev/10. Figure 8-1 shows a graph of the impulse 

response and Fig. 8-2 shows the corresponding frequency response. 
SEE ALSO 

Include files: 


wav.h 
spd.h 
eq fir.h 


BASIC FORMAT 


CALL beqfir( nbands%. ftypez, flen%, bwgit#(0), bmag#(0), bup- 
per#(0), blower#(0), fullhZ, hZ, extZ, dev#, status7Z) 


Where: 


nbands% 
defines the number of bands in the filter, in the range 1 to 10. 


fiype%o 
defines the type of filter to be designed: 0 for Passtop, 1 for Diff, 2 for 
Hilbert, and 3 for Fuser. 
flen% 
describes the number of elements in the filter. 
bwght# (0) 
specifies the weighting function for the band. 
bmag# (0) 
specifies the desired magnitude of the band. 


bupper 
specifies the upper edge of a band. 


blower . 
specifies the lower edge of a band. 


fullh% 
Boolean flag to determine if all or half of the input coefficients are to 
be output. 

h% 
integer identifying the waveform where the impulse response is to be 
stored. 


ext Yo 
integer identifying the waveform where the extremal frequencies are to 
be stored. 


dev# 
peak division from the ideal frequency response. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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Fig. 8-1. Impulse Response 
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Fig. 8-2. Frequency Response. 
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NAME 
err file 
PURPOSE 
Redirects error messages to the specified file pointer. 
SYNOPSIS 


#include "tekspd.h" 
#include <stdio.h> 


ERRORTYPE 
err file(fileptr) 


FILE *fileptr; 
Where: 


fileptr. 
file pointer to which error messages are redirected. 
DESCRIPTION 


err _file redirects error messages to the file pointed to by fileptr. If fileptr is 
NIL or stdin, error messages are redirected to stderr, and a WARNing error 
is issued. The file pointed to by fileptr must be open for write or append. 
File pointers that do not need to be explicitly opened are stdout and stderr. 
It is not possible to inquire about the status of a file pointed to by a file 
pointer. If the file pointer points to an inappropriate file, unspecified errors 
may occur. 


SEE ALSO 
Include files: 


spd.h 
stdio.h 


Signal Processing library functions: 


enabl_fpe 
dsabl_fpe 


Standard library functions: 
fopen 
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BASIC FORMAT 


CALL berrfile(nameS,statuezZ) 


Where: Co 


name$ 
file to which error messages are redirected. 


status% 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
fconv 


PURPOSE 
Performs a non-circular convolution between two real functions using the 
Fast Fourier Transform. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
fconv(x, y, 2) 


WAVEFORM *x, *“y, *Z; 
Where: 


a -. 
pointer to one input waveform representing one real function. 


y- 
pointer to the other input waveform representing the second real func- 
tion. 

2 | 
pointer to the output waveform that will hold the results of the convolu- 
tion. 

DESCRIPTION 
fconv performs a non-circular convolution that can be expressed by the sum- 
mation: 


Kl 
zin) = > xlkly[n-k) for n=0,1,2,...,N-2 
k=0 


where: 
N is the sum of the lengths of waveforms x and y 


K is the length of waveform x 
Nn is an index into waveform z and is used to select an element of y 


For some values of n and k, the index n-k of the array y may be equal to a 
number less than 0 or greater than the length of y (i.e., may be out of 
bounds of y). When this occurs, 0 is used for y[n-k]. 

& The actual computation of the convolved result takes advantage of the cor- 
respondence between time domain convolution and frequency domain mul- 


tiplication. The input arrays are first transformed to the frequency domain 
via the Fast Fourier Transform algorithm. Then a complex multiplication of 
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the resulting arrays is performed, and this result is transformed back to the 
time domain via the Inverse Fast Fourier Transform algorithm. 


To contain the entire result of the convolution, the output waveform must 
have a length equal to or greater than the sum of the lengths of the input 
waveforms minus 1. If the output waveform has a length less than this, it is 
filled with as many data elements as possible, starting with the first. 


All waveforms must be valid and the same waveform can be used for both 
input and output. The data type of each waveform need not be the same. 
fconv performs the computations in double precision and coerces the 
results into the type of the output wveform array. 


The type of each waveform is assumed to be that of the first tuple of the ele- 
ments in its first dimension, and only the first tuple in each element of the 
first dimension of each waveform is used in the computations. 


fconv allocates two temporary arrays of type double when performing the 
FFT and IFFT transformations. The length of each array is the smallest 
power of 2 greater than N - 1. An error will be returned if the required 
amount of memory is not available. 


fconv returns an error code (as defined in the spd.h include file) indicating 
whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 


wav.h 
spd.h 


BASIC FORMAT 


CALL bfconv( xZ, y%Z, 2%, statueZ) 


Where: 
x% 
integer identifying one input waveform representing one real function. 
y% 
integer identifying the other input waveform representing the second 
real function. 
z% 
integer identifying the output waveform that will hold the results of the 
convolution. 


status 7 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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EXAMPLE 

C: 

#include "tekspd.h" 

ERRORTYPE status; 

WAVEFORM *inl, *in2, *out 

char outunits [80]; 

status = fconv(inl, in2, &out); 

strepy(outunits,tup_units(in1,0)); /* V units from inl */ 

streat(outunits,"” * "); 

strcat(outunits,tup_units(in2,0)); /* V units from in2 */ 


status = wf_tunits(outunits,COPY,0,out); /* insert new units */ 
status = wf_dunits(dim_units(inl,0), COPY,0,out); 


dim_scale(out,0) = dim _scale(inl1,0); 
BASIC: 


* SINCLUDE: ‘\tek\spd\include\tekspd.bi' 
inlZ = 1: in2Z = 2: outzZ% 33 


call bfconv(inl%, in2%, out%, status2Z) 
* set units and scaling for waveform outZ 


brtupunits(in1Z,0,inlunits$,inllenZ,statusZ) 
brtupunits(in22,0,in2unitsS,in2lenZ,status2) 


bwftunits(inlunitsSt" * "+in2unitsS,0%,outZ,statusZ) 


brdimunits(in1%,0,inHunits$,inHlenZ,status2Z) 
bwfdunits("inHunitsS,0Z,outZ, statusZ) 


brdimscale(iniZ,0,hsf#,status2Z) 
bwdimscale(outZ,0,hsf#,status2Z) 
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NAME 


fcorr 


PURPOSE 6 


Performs a non-circular correlation between two real functions, using the 
Fast Fourier Transform. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
fcorr(z, yy, z) 


WAVEFORM *x, *y, *z; 


Where: 

x 
pointer to one input waveform representing one real function. 

y: 
pointer to the other input waveform representing the second real func- 
tion. 

Ps 
pointer to the output waveform that will hold the results of the correla- 
tion. 

DESCRIPTION 


fcorr performs a fast correlation on the two input waveform arrays, placing 
the result in the output waveform array. If the two input arrays are the 
same or contain the same data, the operation is called "auto-correlation." If 
the two input arrays are different, the operation is called “cross-correlation." 
fcorr performs a non-circular correlation that can be described by the sum- 
mation: 


i L4 

—— k 
min(L,N) 2, sa i 
forn = (L1),..., 1,0,1,...,(N 1) 


where: 


2, (n) = 


L is the length of waveform x 


N is the length of waveform y 8 
n is an index used to generate the various elements of waveform z 


The output waveform array z contains the results of the correlation: 


z[0] = =za( L+1) 
z[1] = =za( L +2) 
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z{L 1] =za( 1) 
For some values of n and k, the index n+k of waveform array y may be 
equal to a number less than 0 or greater than the length of y (i.e., may be 
out of bounds of y). When this occurs, 0 is used for y[n +k]. 


The fcorr algorithm takes advantage of the correspondence between time- 
domain correlation and frequency-domain, complex-conjugate multiplica- 
tion. The input arrays are first transformed to the frequency domain via the 
Fast Fourier Transform algorithm. Then, a complex-conjugate multiplica- 
tion of the resulting arrays is performed, and the result is transformed back 
to the time-domain via the Inverse Fast Fourier Transform algorithm. 


To contain the entire result of the correlation, the output waveform must 
have a length equal to or greater than the sum of the lengths of the input 
waveforms minus 1. If the output waveform has a length less than this, it is 
filled with as many data elements as possible, starting with the first. 


All waveforms must be valid and the same waveform can be used for both 
input and output. The data type of each waveform need not be the same. 
fcorr performs the computations in double precision and coerces the results 
into the type of the output waveform array. 


The type of each waveform is assumed to be that of the first tuple of the ele- 
ments in its first dimension, and only the first tuple of each element in the 
first dimension of each waveform is used in the computations. The same 
waveform can be used for both input and output. 


fcorr allocates two temporary arrays of type double when performing the 
FFT and IFFT transformations. The length of each array is the smallest 
power of 2 greater than L+N 1. An error will be returned if the required 
amount of memory is not available. 


fcorr returns an error code (as defined in the spd.h include file) indicating 
whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 
spd.h 


wav.h 


BASIC FORMAT 


CALL bfcorr(x%, y%, 2%, statusZ) 
_ Where: 


x% 
integer identifying one input waveform representing one real function. 
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y% 
integer identifying the other input waveform representing the second 
real function. 


z% 

integer identifying the output waveform that will hold the results of the - 
correlation. 

statusZo 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
C: 
#include "“tekspd.h"” 
ERRORTYPE status; 
WAVEFORM *inl, *in2, *out 


char outunits[80]; 


status = fcorr(inl, in2, &out); 


strcepy(outunits,tup_units(in1,0)); /* Vo units from inl */ 
strcat(outunits,” * "); 

strcat(outunits,tup_units(in2,0)); /* V units from in2 */ 

status = wf_tunits(outunits,COPY,0,out); /* insert new units */ @ 
Status = wf_dunits(dim units(in1,0), COPY,0,out); 


dim_scale(out,0) = dim_scale(inl1,0); 


BASIC: 

* SINCLUDE: ‘\tek\spd\include\tekspd.bi’ 
inlZ = 1: in2% = 2: outZ =3 

call bfcorr(ini%, in2Z%, out%, statusZ) 

’ set units and scaling for waveform outZ 
brtupunits(in1Z%,0,inlunitsS,inllenZ,statusZ) 
brtupunits(in22,0,in2unitsS,in2lenZ,statusZ) 


bwftunits(inlunits$+" * "+in2unitsS,0%,out%, statusZ) 


brdimunits(in12%,0,inHunitsS, inHlenZ, statusZ) 
bwfdunits("inHunitsS,0%,out%, statusZ) . 


brdimscale(inlZ%,0,hsf#, statusZ) 
bwdimscale(outZ,0,hsf#,statusZ) 
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NAME 
fft 


PURPOSE 


Performs a Forward Fast Fourier Transform on the complex time domain 
data. 


SYNOPSIS 
#include "“tekspd.h" 


ERRORTYPE 
fft(rtime,itime,rfreq, ifreq) 


WAVEFORM *rtime, *itime, *rfreq, *ifreq; 


Where: 

rtime: 
pointer to the waveform containing the real part of the signal in the 
time domain. 

itime: 
pointer to the waveform containing the imaginary part of the signal in 
the time domain. 


freq: 
pointer to the waveform where the real part of the frequency com- 
ponents will be stored. 

ifreq: 
pointer to the waveform where the imaginary part of the frequency com- 
ponents will be stored. 


DESCRIPTION 
fft uses an FFT algorithm to compute the Discrete Fourier Transform 
on the complex signal stored in rtime and itime. The result is then writ- 
ten into the output arrays, with the real part of the transform going into 
rfreq and the imaginary part into ifreq. The input and output waveforms 
are not required to be different. However, if they are the same, the 
original signal will be overwritten with its transform. 


The length of all four waveforms must be equal and is required to be 
greater than or equal to four. Also, all four waveforms are required to 
be valid, and none can be a NIL pointer. 


If the above conditions are met, the routine will calculate the Discrete 
Fourier Transform of the input signal as follows: 
-j2wnk 


N-l 
X(k] =Soxinle™“ — for k= 0,1,2,..., Nel 
n=0 
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where: = x{n] = Complex input signal 
X[k] = Complex Transform of x[n] 
N = Length of the input signal 
j = Square root of -1.0 


This routine is designed to operate on only a single dimension and a single 
tuple of a waveform. If either an input or output waveform contains more 
than one of these, the information contained in the first will be used 
throughout the routine, and the remainder of the dimensions or tuples will 
not be considered. 


The routine allocates two temporary arrays of type double and length N, 


where N is the length of the input and output waveforms. An error will be 
returned if the required amount of memory is not available. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 


wav.h 
spd.h 


Signal Processing functions: @ 


ifft 
irfft 
rfft 
BASIC FORMAT 
CALL bfft(rtimez, itime%, rfreqZ, ifreq%, statusZ) 


rtime% 
integer identifying the waveform containing the real part of the signal in 
the time domain. 

itime% 
integer identifying the waveform containing the imaginary part of the 
signal in the time domain. 

freq To 
integer identifying the waveform where the real part of the frequency 
components will be stored. 


ifreqZo 
integer identifying the waveform where the imaginary part of the fre- 
quency components will be stored. : 
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status Zo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


6 EXAMPLE 
C: 


#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM *rtime, *itime; 
WAVEFORM *rfreq, *ifreq; 
char units [80]; 


status = createl wf(dim_len(rtime,0), tup_type(rtime,0), &rfreq); 
status = createl_wf(dim_len(rtime,0), tup_type(rtime,0), &ifreq); 


status = fft(rtime, itime, rfreq, ifreq); 


strepy(units,tup_ units(rtime,0)); 7/* V units from rtime */ 
strcat(units,” * "); 

strceat(units,dim units(rtime,0)); /* H units from rtime */ 
status = wf _tunits(units,COPY,0,rfreq); /* insert V units */ 
status = wf_tunits(units,COPY,0,ifreq); /* insert V units */ 


strepy(units,"1 / "); 

strcat(units,dim_ units(rtime,0)); /* H units from rtime */ 
status = wf_dunits(units,COPY,0,rfreq); /* insert H units */ 
status = wf_dunits(units,COPY,0,ifreq); /* insert H units */ 


dim_scale(rfreq,0) = 1.0/(wave_len(rtime)*dim_scale(rtime,0) ); 
dim_scale(ifreq,0) = 1.0/(wave_len(rtime)*dim_scale(rtime,0) ); 


status = we_mult(rfreq, dim_scale(rtime,0) ); 
status = wce_mult(ifreq, dim_scale(rtime,0) ); 


BASIC: 


' SINCLUDE: '\tek\spd\include\tekspd.bi' 
rtimezZ =1: itimez = 2 
rfreqZ =3: ifreqz% = 4 


call bfft(rtime%, imag%, rfreq%, ,ifreq%, status2Z) 
' set vertical units for waveforms rfreqz and ifreq% 


brtupunits(rtime%,0,inVunitsS, inVlenZ,statusZ) 
brdimunits(rtimeZ ,0, inHunitsS, inHlenZ, status2Z) 


bwftunits(inVunitsSt+" * "+inHunitsS,0%,rfreq%,statusZ) 
Se bwftunits(inVunitsSt+" * "+tinHunits$,0%,ifreq%,status2) 


bwfdunits("1 / "+inHunits$,0%,rfreq%Z, statusZ) 
bwfdunits("1 / "+tinHunitsS,0%,ifreq%,statusZ) 


' scale the output waveforms 
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bwavelen(rtimeZ, length&, status2Z) 
brdimscale(rtimeZ, 0, hsf#, statusZ) 


bwdimscale(rfreqz, 0, 1 / (length& * hsf#), status7Z) 
bwdimscale(ifreq%, 0, 1 / (length& * hsf#), status%) a 


bwemult(rfreqz, hsf#, status2Z) 
bwemult(ifreqz, hsf#, statusZ) 
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NAME 
file to wf 


PURPOSE 
Create an original waveform from binary data in a file. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 

file to wf(infile, outwave) 
char *infile; 

WAVEFORM **outwave; 


Where: 
infile: 
name of the file containing waveform data. 


outwave: 
address of pointer to the newly created original waveform. 


DESCRIPTION 


File_to_wf creates a waveform from the data stored in the file named injile 
and puts a pointer to the new waveform in *outwave. File_to_wf works with 
an ASCII or binary ADIF file as written by wf _to_file or wf_to_afile. 


The input file should contain a single waveform. Simple validity checks will 
be done on the file header information. If opening the input file for read- 

ing does not succeed, an appropriate error message will be displayed. Also, 
any error in reading the file, including an unexpected end of file is reported. 


NOTE 


This routine is identical in functionality to afile_to_wf. Both func- 
tions are included for compatibility with earlier versions of SPD. 


file_to_wf issues a FATAL under the following conditions: 
outwave is equal to NIL. 
The input file file cannot be opened for reading. 
An error occurs in reading data from the file. 
& The end of file is encountered before the complete waveform is read in. 


This function returns an error code (as defined in the spd.h include file) 
indicating whether or not it was able to perform correctly. 
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SEE ALSO 
Include files: 


wav.h 
spd.h 


Signal processing functions: 
afile to wf 
wf to _afile 
wf_to file 
APPENDIX E 
BASIC FORMAT 


CALL bfiletowf( in$, outZ, statusZ ) 


Where: 
in$ 
name of the file containing waveform data. 


out% 
integer identifying the newly created original waveform. 


status To 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
Cc: 
#include "“tekspd.h" 
ERRORTYPE status; 
WAVEFORM *wave 
status = file to_wf("mywave.wav" , &wave) 
BASIC: 
" S$INCLUDE: ‘'\tek\spd\include\tekspd.bi’ 


outz =] 
call bfiletowf("mywave.wav" ,outZ,statusZ) 
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NAME 
fr_array 
_ PURPOSE 
Deallocate memory previously allocated to an array. 
SYNOPSIS 
#include "tekspd.h" 


fr_array(arrptr) 
BYIE *arrptr; 


Where: 


arrpir: 
pointer to array to be deallocated. 
DESCRIPTION 


fr_array deallocates the memory allocated by mk_array. The signal process- 
ing and graphics libraries call this function to deallocate all data arrays and 
the array portion of waveforms. 


ly allocate memory. If an application program requires special memory 
management processing for arrays, this function along with its dual 
mk_array may be modified. 
SEE ALSO 
Include files: 
spd.h 


wav.h 


e@ fr_array is a low level memory allocation function that calls malloc to actual- 


Signal processing functions: 
fr_block 


fr_string 
mk_array 
mk_block 
mk_string 
Standard library functions: 


malloc 


free 
© BASIC FORMAT 


Fr _array is not available from BASIC. 


Signal Processing & Display 8-77 


Si gnal Processing 
Jr_block 


NAME 
fr_block 


PURPOSE @ 


Deallocate memory previously allocated to memory block. 


SYNOPSIS 
#include "tekspd.h" 


fr_block(blkptr) 
BYTE *bikptr; 
Where: 
blkptr: 
pointer to block of memory to be deallocated. 
DESCRIPTION 
fr_block deallocates the memory allocated by mk_block. 


fr_block is a low level memory allocation function that calls malloc to actual- 

ly allocate memory. If an application program requires special memory 

management processing, this function along with its dual mk_block may be 

modified. ® 
SEE ALSO 

Include files: 


spd.h 
wav.h 


Signal processing functions: 
fr_array 
fr_string 
mk_array 
mk_block 
mk_string 

Standard library functions: 
malloc 
free 

BASIC FORMAT 


Fr_block is not available from BASIC. 6 
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NAME 
fr_string 
PURPOSE 
Deallocate memory previously allocated to a character string. 


SYNOPSIS 


#include "“tekspd.h" 
fr_string(strptr) 
char *strptr; 


Where: 
strptr: 
pointer to string to be deallocated. 
DESCRIPTION 
jr_string deallocates the memory allocated by mk_string. 


fr_string is a low level memory allocation function that calls malloc to actual- 
ly allocate memory. If an application program requires special memory 
management processing for strings, this function along with its dual 


© mk_string may be modified. 
SEE ALSO 


Include files: 


spd.h 
wav.h 


Signal processing functions: 


fr_array 
fr block 
mk_array 
mk_block 
mk_string 


Standard library functions: 


malloc 
free 


BASIC FORMAT 
© Fr_string is not available from BASIC. 
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NAME 
free wf 


PURPOSE @ 
Deallocate a waveform 


SYNOPSIS 
#include "tekspd.h" 


ERRORTY PE 
free_wf(wave) 


WAVEFORM *wave; 


Where: 


wave: 
pointer to the waveform to be released. 


DESCIPTION 


If the waveform is a valid waveform and if the bit flags indicate that the 

structure space was allocated by one of the waveform utilities and the num- 

ber of subordinate waveforms is zero, the waveform space is deallocated. 

Also, if the waveform is an original waveform, the array is deleted if the bit @ 
flags indicate that the array space was allocated by one of the waveform 

utilities. Otherwise, the subordinate waveform counter of its previous 

waveform is decremented. 


If wave is already NIL, no action is taken. If wave is not a valid waveform, 
free_wf issues a FATAL error. If the waveform cannot be deallocated (the 
bit flags do not indicate that the structure space was allocated by one of the 
waveform utilities or the subordinate waveform counter is not zero), free_wf 


issues a WARNing error. No WARNing error is issued if the array cannot 
be deallocated; it is assumed that the array was associated with the 
waveform with arr_to_wf() or arrl_to_wf(). 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 
SEE ALSO 
Include files: 
spd.h 


wav.h @& 
Signal processing functions: 
arr to wi 
arrl_to wf 
_ create_wf 
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createl wf 
dim_reorder 
make_subwf 
make _target 
tup_ reorder 
zone_dim 


BASIC FORMAT 


CALL bfreewf( wave%Z,status2Z) 


Where: 


wave % 
integer identifying the waveform to be released. 


status Yo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
ifft 


PURPOSE _ 


Performs a Forward Fast Fourier Transform on the complex frequency 
domain data. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
ifft(rfreq,ifreq,rtime,itime) 


WAVEFORM *rfreq, *ifreq, *rtine, *itime; 

Where: 

freq: — 
pointer to the waveform where the real part of the signal in the frequen- 
cy domain. 

ifreq: 
pointer to the waveform where the imaginary part of the signal in the 
frequency domain. - 

rtime: 
pointer to the waveform where the real part of the time domain com- 
ponents will be stored. 

itime: 
pointer to the waveform where the imaginary part of the time domain 
components will be stored. 


DESCRIPTION 


ifft uses an FFT algorithm to compute the Inverse Discrete Fourier Trans- 
form on the complex signal stored in rfreq and ifreq. The result is then writ- 
ten into the output arrays, with the real part of the transform going into 
rtime and the imaginary part into itime. The input and output waveforms 
are not required to be different. However, if they are the same, the original 
signal will be overwritten with its inverse transform. 


The length of all four waveforms must be equal and is required to be 
greater than or equal to four. Also, all four waveforms are required to be 


valid, and none can be a NIL pointer. ® 
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crete Fourier Transform of the input signal as follows: 


N-] j2mnk 
Xin] = 2 Xlkle® forn= 0,1,2,..., Nel 


where: X[k] = Complex input signal 
x(n] = Complex Inverse Transform of X[k] 
N = Length of the input signal 
j = Square root of -1.0 


This routine is designed to operate on only a single dimension and a single 
tuple of a waveform. If either an input or output waveform contains more 
than one of these, the information contained in the first will be used 
throughout the routine, and the remainder of the dimensions or tuples will 
not be considered. 


The routine allocates two temporary arrays of type double and length N, 
where N is the length of the input and output waveforms. An error will be 
returned if the required amount of memory is not available. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 


wav.h 
spd.h 
Signal Processing functions: 
fft 
irfft 
rfft 


BASIC FORMAT 
CALL bifft(rfreqZ, ifreq%, rtimeZ%, itimeZ, status7Z) 


Where: 

rfreq %o 
integer identifying the waveform containing the real part of the signal 
in the frequency domain. 

ifreq To 
integer identifying the waveform containing the imaginary part of the 
signal in the frequency domain. 

rtimeZ 
integer identifying the waveform where the real part of the time domain 
components will be stored. 
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itime% 
integer identifying the waveform where the imaginary part of the time 
domain components will be stored. & 


status Zo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
C: 


#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM *rfreq, *ifreq; 
WAVEFORM *rtime, *itime; 
char units[80]; 


status = createl wf(dim_len(rfreq,0), tup_type(rfreq,0), &rtime) ; 
status = createl wf(dim_len(rfreq,0), tup_type(rfreq,0), &itime); 


Status = ifft( rfreq, ifreq, rtime, itime); 


strcpy(units,tup_units(rfreq,0)); /* V units from rfreq */ 

streat(units,"” * "); 

streat(units,dim units(rfreq,0)); /* H units from rfreq */ 

status = wf_tunits(units,COPY,0,rtime); /* insert new units */ _ 
status = wf_tunits(units,COPY,0,itime); /* insert new units */ 


status = wc_div(itime, wave_len(rfreq) * dim_scale(rfreq,0) ); 
status = wc_div(rtime, wave_len(rfreq) * dim_scale(rfreq,0) ); 


BASIC: 


* SINCLUDE: ‘'\tek\spd\include\tekspd.bi’ 
rfreqz =3: ifreqz% = 4 
rtimez =1: itimeZz = 2 


call bifft(rfreq%, ifreq%, rtimeZ%, itimeZ, statusZ) 


‘ set vertical units for waveforms rtimeZ and itimeZ 
brtupunits(rfreq%,0,inVunitsS,inVlenZ,status2Z) 
brdimunits(rfreqZ%,0,inHunitsS,inHlenZ,statusZ) 


bwftunits(inVunitsSt+" * "tinHunitsS,0Z,rtimeZ,status2Z) 


bwftunits(inVunits$+" * "+inHunitsS ,0Z,itime%,statusZ) 


bwfdunits("1 / "+tinHunitsS,0%,rtimeZ, status2Z) 


' set horizontal units for waveforms rtimeZ and itime% 
bwfdunits("1 / "tinHunitsS,0%,itimeZ,statusZ) © 


* scale the output waveforms 
bwavelen(rfreq%z, length&, status2Z) 
brdimscale(rfreqz, 0, hsf#, statusZ) 


bwdimscale(rtimez, 0, 1 / (length& * hsf#), statusZ) 
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bwdimscale(itimeZ, 0, 1 / (length& * hsf#), statusZ) 


bwemult(rtimez%, hsf#, status2Z) 


¢ bwemult(itime%, hsf#, status2Z) 
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NAME 
integrate 


PURPOSE ®@ 


Performs integration on a waveform and stores the integrated result in a 
waveform. 


SYNOPSIS 
#include "“tekspd.h" 


ERRORTYPE 
integrate(in, eoaa, out) 


WAVEFORM *in; 
int eoaa; 
WAVEFORM *out; 
Where: 
in: 
pointer to the waveform containing data to be integrated. 


eoaa: 
end-of-array algorithm to use for end effects. € 


out: 
pointer to the waveform containing data after integration. 
DESCRIPTION 


integrate integrates the waveform pointed to by im and stores the integrated 
result in the waveform pointed to by out using Simpson’s method: 


out_arr[0] = 0 
forn > 1 andn odd, 


out_arr{n] = outcarr{n-1]+~12 rrin-1) + ‘ rrinj-inarrin+t] 
| l 


out_arrindl] = out_arrin] +—i0—_arrnl) + 81 : +5in—arrin+l] 
7 I 


where 


out_arr is the output waveform array 
in_arr is the input waveform array 
N is the length of the shortest waveform array r 


For N odd, the above formula will work until n = N - 2; at this point, 
out_arr[N-1] has been found and the algorithm is completed. For N even, 
the above formula works until n = N - 3; at this point, out_arr[N-2] has 
been found and out_arr[N-1] must be obtained. To compute out_arr[N-1], 
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eoaa is used to find a point outside of the array bounds, and Simpson’s 
method is then used as before. 


If the two waveforms are the same, the integrated result overwrites the 
input waveform. If the waveform arrays are not the same size, the output 
waveform array is valid only to the length of the shortest array. 


eoaa is used when the length being integrated is even, and, to finish the al- 
gorithm, in_arr[N] is needed. If the input array is longer than the output 
array, out_arr[N-1] is calculated using the existing in_arr[N]. If this is not 
the case, in_arr[N] is given a value according to which eoaa was specified. 
See page 8-2 for details on the use of the eoaa parameter. 


If a number becomes too large for the data type, the position in the array is 
filled with the maximum allowable number and an error message is sent. 
Similarly, overflow with negative numbers results in the minimum allowable 
number being stored and indication of overflow to the user. The waveform 
arrays must be of length at least three, and both waveforms must be valid. 
Information is taken from the first dimension of the input waveform and is 
placed in the first dimension of the output waveform. Data type informa- 
tion is taken from the first tuple of both the input and output waveform ar- 
rays. The sampling interval of time, the distance between consecutive 
points along the x-axis, is expected to be one. If this is not the case, the 
& results must be scaled by the proper amount. To scale the results, multiply 
each output waveform array element by the distance between the successive 
data points along the x-axis. 


The function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 
SEE ALSO 
Include files: 
sp.h 
spd.h 
wav.h 


BASIC FORMAT 


CALL bintegrate (in%, eoaa%, out%, statusZ) 


Where: 
inZo 
@ integer identifying the waveform containing data to be integrated 


eoaa% 
end-of-array algorithm to use for end effects. Should be one of the pre- 
defined constants REPEAT%, BOUNCE%, INVERT%, WRAP%, or 
ZERO%. See page 8-2 for details about the meaning of these constants. 
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outTo 
integer identifying the waveform containing data after integration 


status 
integer indicating the execution status of the function. Result will be © 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
Cc: 
#include "tekspd.h" 
ERRORTYPE status; 


WAVEFORM *in, *out 
char units[80]; 


status = integrate(in, EA_REPEAT, out); 


strepy(units,tup_units(in,0)); /* V units from in */ 
streat(units," * "); 
strcat(units,dim_units(in,0)); /* H units from in */ 


status = wf_tunits(units,COPY,0,out); /* insert units */ 
status = wf_dunits(dim_units(in,0),COPY,0,out); 


dim_scale(out,0) = dim_scale(in,0); 


status = wc_mult(out, dim_scale(in,0) ); ® 


BASIC: 


" SINCLUDE: ‘\tek\spd\include\tekspd.bi’ 
ing = 1: outZ =2 


call bintegrate(inZ, REPEATZ, ,out%, status2Z) 


' set vertical units for outzZ 


brtupunits(in%,0,inVunitsS,inVlenZ,statusZ) 
brdimunits(inZ,0,inHunitsS,inHlen%Z,statusZ) 


bwftunits(inVunitsS+" * "+inHunitsS,0Z,outZ,status2Z) 


" set horizontal units for outZ 
bwfdunits (inHunitsS,0%,out%, statusZ) 
* scale the output waveform 
brdimscale(inZz, 0, hsf#, status2Z) 
bwdimscale(outZ, 0, hsf#, statusZ) 


bwemult(inZ, hsf#, status2Z) } 
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NAME 
irfft 
PURPOSE 
Performs an Inverse Fast Fourier Transform on frequency domain data 
that will be purely real in the time domain. 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
irfft(rfreq,ifreq, time) 


WAVEFORM *rfreq, *ifreq, *tine; 
Where: 


rfreq: 
pointer to the waveform containing the real part of the signal in the fre- 
quency domain. 


ifreq: 
pointer to the waveform containing the imaginary part of the signal in 
the frequency domain. 


time: 
pointer to the waveform where the time domain components will be 
stored; it will contain only real terms. 


DESCRIPTION 


irfft uses an FFT algorithm to compute the Inverse Discrete Fourier Trans- 
form on the complex signal stored in rfreq and ifreq. The result is then writ- 
ten into the output array, time, as a signal consisting of only real terms. 


The length of time is required to be greater than or equal to eight. The 
length of rfreq and ifreq must be equal to one more than half the length of 
time. The input and output waveforms are required to be different, due to 
the different lengths involved. Also, all three waveforms must be valid, and 
none can be a NIL pointer. 


The process of computing the Inverse Discrete Fourier Transform can be 
thought of in terms of the following equation: 


N-] jamnk 
Xin] “42, XtkleN  forn= 0,1,2,..., Nl 


For real time domain signals, the frequency domain representation consists 


of an even function for the real part and an odd function for the imaginary 
part. Because of this relationship, the input real and imaginary waveform, 
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X[k], contains only the first N/2+1 elements of the complete frequency se- 
quence. 

This routine is designed to operate on only a single dimension and a single 
tuple of a waveform. If either an input or output waveform contains more 
than one of these, the information contained in the first will be used 
throughout the routine, and the remainder of the dimensions or tuples will 
not be considered. 


The routine allocates two temporary arrays of type double and length N +1, 
where N +1 is the length of the input waveforms. An error will be returned 
if the required amount of memory is not available. 

This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 


wav.h 
spd.h 


Signal Processing functions: 
fft 
ifft 
irfft 


BASIC FORMAT 


CALL birfft(rfreq%, ifreqz%, timeZ, statusZ) 


Where: 
rfreq7o 


integer identifying the waveform containing the real part of the signal in 
the frequency domain. 

ifreq7o 
integer identifying the waveform containing the imaginary part of the 
signal in the frequency domain. 


time% 
integer identifying the waveform where the time domain components 
will be stored; it will contain only real terms. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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Br 
#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM ‘*rfreq, *ifreq; 


WAVEFORM *time; 
char units [80]; 


status = createl wf( (dim_len(rfreq,0)-1) * 2, tup_type(rfreq,0), 
&time); 


Status = irfft( rfreq, ifreq, time); 

strcpy(units,tup units(rfreq,0)); /* V units from rfreq */ 
strcat(units," * "); 

strceat(units,dim_units(rfreq,0)); /* H units from rfreq */ 
status = wf_tunits(units,COPY,0,time); /* insert V units */ 
strepy(units,"1 / "); 

streat(units,dim_units(rfreq,0)); /* H units from rfreq */ 
Status = wf_dunits(units,COPY,0,time); /* insert H units */ 


dim_scale(time,0) = 1.0/(wave_len(time)*dim_scale(rfreq,0) ); 


status = wc mult(time, dim_scale(rfreq,0) ); 


BASIC: 

' SINCLUDE: '\tek\spd\include\tekspd.bi' 
rfreqz =1: ifreqz = 2 

timez =3 

call birfft(rfreqZ, ifreqZ, timeZ, status2Z) 

’ set vertical units for waveform timeZ 
brtupunits(rfreqz,0,inVunitsS,inVlenZ,status2) 
brdimunits(rfreq%,0,inHunitsS,inHlenZ,statusZ) 


bwftunits(inVunitsS+" * “+inHunitsS,0%,time%,statusZ) 


’ set horizontal units for waveform time%Z 
bwfdunits("1 / "tinHunitsS,0%,timeZ, statusZ) 


* scale the output waveforms 
bwavelen(timeZ, length&, statusZ) 
brdimscale(rfreqZ, 0, hsf#, status2) 

6 bwdimscale(timez, 0, 1 / (length& * hsf#), status2) 


bwemult(time%, hsf#, statusZ) 
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NAME 
make_subwf 


PURPOSE 
Creates a subordinate waveform that is a copy of another waveform. The 
new waveform is a subordinate waveform of the source waveform. 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
make_subwf (wave, subwave) 


WAVEFORM *wave; 
WAVEFORM **subwave; 


Where: 


wave: 
pointer to the waveform to be copied. 
subwave: 
address of the pointer to the subordinate waveform to be created. 


DESCRIPTION 


make_subwf allocates memory space for a new waveform structure and its 
associated substructures. It returns the address of the new subordinate 
waveform in subwave. 


This function is used for making minor changes in a waveform chain. sub- 
wave is made subordinate to wave and the subordinate counter of wave is 
incremented. 


String fields (titles, notes, dimension labels, dimension units, tuple labels 


and tuple units) for sebwave are LINKed to the string information in wave. 
That is, the pointer to the string in wave is copied to subwave, but the cor- 


responding bit in the bit flags field is reset indicating that no memory was 
allocated for subwave to contain the string. 


The information in the new WAVEFORM structure is copied from the 
source except: 


The pointer to the previous waveform is set to wave. 
The number of subordinate waveforms is set to zero. 


The bit flags are set to show that the structure space was allocated by 
one of the waveform utilities and can, therefore, be released by them. 


The string field bit flags (title and notes) are set to 0. 
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The pointer to the substructures containing dimension information 
points to the W_DIM structure for the first dimension of the new 
waveform. 

The pointer to the substructures containing the tuple information 


points to the W_TUPLE structure for the first tuple of the new 
waveform. 


The information in the W_DIM structures and the W_ TUPLE structures of 
the new waveform is copied from the source, except the bit flags which are 
set to 0. 


make_subwf issues a FATAL error if: 


wave is not a valid waveform. 


There is not enough free memory available for the new waveform 
structures. 


If a FATAL error occurs, *subwave is set to NIL. 


SEE ALSO 
spd.h 
wav.h 

NOTES 


If subwave points to the address of wave upon function entry, it is then the 
user’s responsibility to note the waveform structure previously associated 
with wave. 


BASIC FORMAT 


CALL bmakesubwf( waveZ%, subwaveZ, statusZ ) 


Where: 


wave Yo 
integer identifying the waveform to be copied. 


subwave% . 
integer identifying the subordinate waveform to be created. 


status Zo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
make target 


PURPOSE 


Creates an original waveform that is a copy of another waveform except for 
the array data. 


SYNOPSIS 
#include "“tekspd.h" 


ERRORTYPE 
make target (inwave, outwave) 


WAVEFORM *inwave; 
WAVEFORM **outwave; 


Where: 


inwave: 
pointer to the waveform to be copied. 


outwave: 
address of the pointer to the new waveform to be created. 


DESCRIPTION © 


make_target allocates memory space for a new waveform structure and its 
associated substructures and array. It returns the address of the new 
waveform in outwave. 


The new waveform is an original waveform and the array of the new 
waveform is contiguous. However, the new waveform array is zero filled; it 
is not filled with data from the source waveform array. 


make_target is used to create an output waveform to be passed as a 
parameter to a signal processing function that needs a target waveform. 


The information in the new WAVEFORM structure is copied from the 
source except: 


The pointer to the previous waveform is set to NIL. 
The number of subordinate waveforms is set to zero. 


The title pointer is set to a copy of the title string (if any). It is set to 
NIL if the source waveform does not have a title. 


The notes pointer is set to a copy of the notes string (if any). It is set to 
NIL if the source waveform does not have a notes string. 


The bit flags are set to show that the structure space, array space and 
any title or note strings were allocated by one of the waveform utilities 
and can, therefore, be released by them. 
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The array pointer points to the first tuple of the first element of the new 
waveform array. 


The pointer to the substructures containing dimension information 
points to the W_DIM structure for the first dimension of the new 
waveform. 


The pointer to the substructures containing the tuple information 
points to the W_TUPLE structure for the first tuple of the new 
waveform. 


The information in the W_DIM structures of the new waveform is copied 
from the source except: 


The bit flags are set to show that any label or units string were copied 
by one of the waveform utilities and can therefore be released by them. 
If both the label and units strings were NIL then the bit flags are set to 
zero. 


The increment to the next element is calculated such that the increment 
for the last dimension is the data element size; and then working back- 
wards, the increment for each dimension, n, is the increment for dimen- 
sion n+1 times the length of dimension n+1. 


The label pointer is set to a copy of the label string (if any). It is set to 
NIL if the source waveform does not have a label string for the cor- 
responding dimension. 


The units pointer is set to a copy of the units string (if any). It is set to 
NIL if the source waveform does not have a units string for the cor- 
responding dimension. 


The information in the W_TUPLE structures of the new waveform is 
copied from the source except: 


The bit flags are set to show that any label or units string were copied 
by one of the waveform utilities and can therefore be released by them. 
If both the label and units strings were NIL then the bit flags are set to 
zero. 


The byte offset from the first tuple is calculated such that the offset for 
the first tuple is zero; and then working forwards, the offset for each 
tuple, n, is the offset for tuple n-1 plus the byte length of the data type 
of tuple n-1. 


The label pointer is set to a copy of the label string (if any). It is set to 
NIL if the source waveform does not have a label string for the cor- 
responding tuple. 


The units pointer is set to a copy of the units string (if any). It is set to 
NIL if the source waveform does not have a units string for the cor- 
responding tuple. 
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make_target issues a FATAL error if: 


inwave is not a valid waveform. 


There is not enough free memory available for the new waveform struc- @ 
tures. 


There is not enough free memory available for the new array. 
If a FATAL error occurs, *outwave is set to NIL. 


SEE ALSO 
spd.h 
wav.h 


NOTES 
If subwave points to the address of wave upon function entry, it is then the 
user’s responsibility to note the waveform structure previously associated 
with wave. 

BASIC FORMAT 


CALL bmaketarget( inwaveZ, outwave%, statusZ ) 


Where: 


inwave % 
integer identifying the waveform to be copied. 


outwave % 
integer identifying the new waveform to be created. 


status Yo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
meanstd 


PURPOSE 


Finds the mean, standard deviaton, variance, and root-mean-square of a 
waveform. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
meanstd (wave ,mean,std,var,rms) 


WAVEFORM *wav; 
double *mean, *std, “var, “rms; 


Where: 


wav: 
pointer to the waveform to use in calculations. 


mean: 
pointer to the location where the mean will be stored. 


std: 
pointer to the location where the standard deviation will be stored. 


var, 
pointer to the location where the variance will be stored. 


LLY 
pointer to the location where the root-mean-square will be stored. 


DESCRIPTION 


meanstd finds the mean, standard deviation, variance and root-mean-square 
of the waveform and places these results into the locations specified by 
mean, std, var, and rms, respectively. If any of the input pointers, mean, std, 
var, or rms, are NIL upon input, the respective value will be suppressed and 
it will not be returned to the user. 


This routine is designed to operate on multi-dimensional waveforms which 
contain only a single tuple. If the input waveform contains more than a 
single tuple, all information will be taken from the first and the remainder 
will not be considered. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 
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SEE ALSO 
Include files: 


spd.h 
wav.h 
BASIC FORMAT | 


CALL bmeanstd ( wavZ, mean#, std#, var#, rms#, status2Z) 


Where: 


wav% 
integer identifying the waveform to use in the calculations. 


mean# 
double identifying the location where the mean will be stored. 


std# 
double identifying the location where the standard deviation will be 
stored. 


var# 
double identifying the location where the root-mean-square will be 
stored. 


status To 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


NOTE 


The meanstd function assumes that the waveform passed to it con- 
tains an integral number of cycles. If this is not true, the function 
will not complain but the values returned will be incorrect. 


EXAMPLE 
hot 
#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM “*wave; 
double mean, std, var, rms; 
status = meanstd(wave, &mean, &std, &var, &rms); 


BASIC: 


' SINCLUDE: '\tek\spd\include\tekspd.bi' © 


wavez = 1 


call bmeanstd(waveZ, mean#, std#, var#, rms#, statusZ) 
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NAME 
minmax 
PURPOSE 
Find the minimum and maximum values of a waveform. 


SYNOPSIS 
#include "tekspd.h” 


ERRORTYPE 
minmax(wave, minval, maxval, minloc, maxloc) 


WAVEFORM *wave; 
double *minval, *maxval; 
long minloc({], maxloc[]; 


Where: 


wave: 
pointer to the waveform to be searched for the minimum and maximum. 


minval: 
pointer to the location where the minimum value will be stored. 


maxval: 
pointer to the location where the maximum value will be stored. 


minloc: 
pointer to the array where the waveform element indices of minval will 
be stored. 


maxloc: 
pointer to the array where the waveform element indices of maxval will 
be stored. 


DESCRIPTION 


minmax finds the minimum and maximum elements in the waveform. The 
minimum and maximum values are stored at the locations pointed to by 
minval and maxval, respectively. The location of the minimum and maxi- 
mum values are stored as element indices in the arrays min/oc and maxloc. 
The lengths of these arrays must be greater than or equal to the number of 
dimensions in wave. If a minimum or maximum value occurs at more than 
one location in the waveform, the location of the first value is output. 


If any of the input pointers, »inval, maxval, minloc, or maxloc, are NIL 
upon input, that output will be suppressed and the information will not be 
available to the user. 


This routine is designed to operate on multi-dimensional waveforms that- 
contain only a single tuple. If the input waveform contains more than a 
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single tuple, all information will be taken from the first and the remainder 
will not be considered. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 


spd.h 
wav.h 


BASIC FORMAT 


CALL bminmax( wavZ, minval#, maxval#, minloc&, maxloc&, statusZ ) 


Where: 


wav% 
the waveform to be searched for the minimum and maximum. 


minval# 
the location where the minimum value will be stored. 


maxval# 
the location where the maximum value will be stored. 


minloc& 
the first element of the array where the waveform element indices of 
minval will be stored. For a one dimension waveform, minloc& will 
simply be a long integer. 

maxloc& 
the first element of the array where the waveform element indices of 
maxval will be stored. For a one dimension waveform, maxloc& will 
simply be a long integer. 

status To 
integer indicating the execution status of the function. Result will be 


one of NOERROR%, WARN%, FATAL%, or CRASH%. 
EXAMPLE 
C (one dimension): 
#include “tekspd.h" 
ERRORTYPE status; 
WAVEFORM *wave; /* a one dimension array */ 
double min, max; 


long minloc, maxloc; 


Status = minmax(wave, &min, &max, &minloc, &maxloc); 
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C (multi-dimension): 


#include "tekspd.h" 

ERRORTYPE status: 

WAVEFORM *wave; /* a three dimension array */ 
double min, max; 

long minloc[3]), maxloc[3]; 


status = minmax(wave, &min, &max, &minloc, &maxloc); 


BASIC (one dimension): 


* SINCLUDE: '\tek\spd\include\tekspd.bi' 
wavez = 1 ' waveZ is a one dimension array 


call bminmax(waveZ, min#, max#, minloc&, maxloc&, status2Z) 
BASIC (multi-dimension): 

*’ SINCLUDE: '\tek\spd\include\tekspd.bi' 

wavezZ = 1 ' waveZ is a three dimension array 

dim minloc&(3) 


dim maxloc&(3) 


call bminmax(waveZ, min#, max#, minloc&(0), maxloc&(0), statusZ) 
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NAME 
mk_array 


PURPOSE 
Allocate memory for arrays. 


SYNOPSIS 
#include "tekspd.h" 


BYTE 
*mk_array(numelem, bytesize) 
long numelem,bytesize; 


Where: 


numelem: 
number of elements to be allocated for array. 
bytesize: 
size of an array element in fundamental machine units (bytes). 


DESCRIPTION 
mk_array allocates space for data arrays. The signal processing and 
graphics libraries call this function to allocate all data arrays and the 
array portion of waveforms. A pointer to the beginning of the array 
area allocated is returned. If there is insufficient memory available, NIL 
is returned. 


mk_array is a low level memory allocation function that calls malloc to 
actually allocate memory. If an application program requires special 
memory management processing for arrays, this function along with its 
dual fr_array may be modified. 


SEE ALSO 
Include files: 


spd.h 
wav.h 
Signal processing functions: 


fr_array 
fr_block 
fr_string 
mk_block 
mk_string 
Standard library functions: 
malloc 
free 
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BASIC FORMAT 
Mk array is not available from BASIC. 
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NAME 
mk_block 


PURPOSE @ 


Allocate a block of memory. 


SYNOPSIS 
#include "tekspd.h" 


BYTE 
*mk_block(size) 
unsigned size; 


Where: 


size: 
size (in bytes) for the block of memory to be allocated. 


DESCRIPTION 


mk_block allocates a block of memory of size bytes. This function is in- 
tended for allocating small blocks of memory. The signal processing library 
uses it to allocate space for waveform data structures. A pointer to the 


beginning of the memory allocated is returned. If there is insufficient 
memory available, NIL is returned. 


mk_block is a low level memory allocation function that calls malloc to ac- 
tually allocate memory. If an application program requires special memory 
management processing for arrays, this function along with its dual fr_block 
may be modified. 


SEE ALSO 


Include files: 


spd.h 
wav.h 


Signal processing functions: 


fr_array 
fr_block 
fr_string 
mk_array 
mk_string 


Standard library functions: & 
malloc 


free 
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BASIC FORMAT 
Mk_block is not available from BASIC. 
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NAME 
mk_string 


PURPOSE © 
Allocate memory for character strings. 


SYNOPSIS 
#include "tekspd.h”" 


char 
*mk_string(nchars) 
int nchars; 


Where: 


nchars: 
number of characters to allocate for a string. 


DESCRIPTION 


mk_string allocates memory for a character string containing nchars charac- 
ters (including any NULL terminator). The signal processing library uses it 
to allocate memory for strings. A pointer to the beginning of the string area 
is returned. If there is insufficient memory available, NIL is returned. 
mk_string is a low level memory allocation function that calls malloc to ac- 
tually allocate memory. If an application program requires special memory 


management processing for strings, this function along with its dual fr_string 
may be modified. 


SEE ALSO 
Include files: 
spd.h 


wav.h 
Signal processing functions: 


fr_array 
fr_block 
fr_string 
mk_array 
mk_block 


Standard library functions: 


malloc 
free 
BASIC FORMAT 
MK string is not available from BASIC. 
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NAME 
pls amp 


PURPOSE 


Measures the amplitude of a rectangular pulse at the pulse center and 
reference points. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
pls_amp(wave, lead, trail, ref_index, n_av, eoaa, ctr_level, 
ref_level) 


WAVEFORM *wave; 

long lead, trail, ref_index; 
int n_av, eoaa; 

double *ctr_level, *ref_level; 


Where: 


wave: 
pointer to waveform containing data to be examined 


lead: 
index in wave of the approximate leading transition edge 
trail: 
index in wave of the approximate trailing transition edge 
ref index: 
the index in wave around which n_av elements are averaged to deter- 
mine ref_level. 


nav: 
number of elements around ref_index and the center of the pulse to 
compute ref level and cir_level 


eoaa: 
end of array algorithm to use in case computations require data from 
outside the waveform bounds 


ctr level: 
pointer to variable in which the pulse level at the pulse center is 
returned 


ref level: 
pointer to a variable in which the reference level is returned 


DESCRIPTION 


pls_amp first averages n_av points around ref_index and stores the result in 
the address specified by ref_level. (If ref_index is at the beginning or end of 
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the waveform, eoaa is used to obtain the necessary data for averaging.) The 

center of the pulse is determined as being approximately halfway between 

the indices of /ead and trail. The center level, ctr_level, is computed as the 

average of n_av elements around this approximate center location. © 


A fatal error is issued if any of the following criteria are not met: 
wave must be a valid waveform. 
lead must be less than trail. 
lead, trail, and ref_index must be within bounds of waveform wave. 
ref_index must lie outside the region between lead and trail. 

A warning error is issued if any of the following criteria are not met: 
n_av should be at least 1. If it is not, it is set to 1. 


eoaa should be EA_REPEAT, EA BOUNCE, EA_INVERT, EA_WRAP, 
or EA_ZERO. See | page 8-2 for an explanation of these values. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 


SEE ALSO 
Include files: 


wav.h 
spd.h @ 
sp.h 


Signal processing library function: 
pls_edge 
BASIC FORMAT 


CALL bplsamp(wavez, lead&, trail&, ref_index&, n_av%, eoaaz, 
ctr_level#, ref_level#, status%) 


Where: 


wave J: 
integer identifying the waveform to be examined. 


lead&: 

index in wave of the approximate leading transition edge. 
trail&: 

index in wave of the approximate trailing transition edge. 


ref index&: 
index in wave around which n_av elements are averaged to determining Go 
ref_level. 


n_av% 
number of elements around ref_index and the center of the pulse to 
compute ref_level and ctr level. 
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eoaa% 
end of array algorithm to use in case computations require data from 
outside the waveform bounds. Should be one of the pre-defined con- 
stants REPEAT%, BOUNCE%, INVERT%, WRAP%, or ZERO%. See 
page 8-2 for an explanation of these values. 


ctr_level# 
the pulse level at the pulse center (output). 


ref _level# 
the reference level (output). 


status To: 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
pls_calc 


PURPOSE © 
Calculates parameters describing a pulse from given values for high and 
low signal level. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
pls_calc(wave, l_index, r_index, dir, top, bottom, n, eoaa, 
tlevel, params) 


WAVEFORM *wave; 

long l_index, r_index; 
int dir, n, eoaa; 

double top, bottom; 
double *tlevel, “params; 


Where: 


wave: 
pointer to waveform containing data to be examined. 
I index: Go 
leftmost index in wave to be examined. 
r index: 
rightmost index in wave to be examined. 
dir: 
direction of search (RIGHT or LEFT). 
top: 
value of predetermined high level of the signal. 


bottom: 
value of predetermined low level of the signal. 


number of elements that must stay crossed for the crossing to be valid. 
eoaa: 
end-of-array algorithm to use if needed. 
tlevel: 
pointer to a three-element double array containing the percentage 
levels for the proximal, mesial, and distal points. 8 
params: 
pointer to an eleven-element double array in which the calculated 
parameters are returned. 
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DESCRIPTION 
pls_calc calls other routines to calculate the parameters of a pulse and 
returns the information in the array pointed to by params as follows: 
_ params(0] = pulse amplitude 
params[1] = msetime 
params[2] = rising proximal point 
params[3] = rising mesial point 
params[4] = rising distal point 
params[5] =  falltime 


params[6] = falling distal point 
params[7}] = falling mesial point 
params[8] = falling proximal point 
params[9] = duty factor (fractional) or -1 
params{10] = period or pulse width 


top and bottom are specified by the user and are the basis for calculating all 
the parameters. If the user desires for top and bottom to be determined by a 
histogram method, p/s_meas() should be used. 


The first three elements pointed to by tlevel should contain the fractional 
levels for calculating the proximal, mesial, and distal points, in that order. If 
the contents of those three elements are not values such that 0 < = ¢level[0] 
< tlevel[1] < tlevel{[2] < = 1 is true, the following default levels are used: 


proximal : 10 (10%) 
mesial: 50 (50%) 
distal: 90 (90%) 


Risetime is the number of waveform samples between the proximal and dis- 
tal points on the rising edge. Falltime is the number of waveform samples 
between the distal and proximal points on the falling edge. The period is 
the number of waveform samples between mesial points on successive 
rising or falling transitions. The duty factor is the ratio of the number of 
waveform samples during which the amplitude is above the mesial point to 
the period. 


If the pulse waveform is not periodic (i.e., fewer than three edges between 
l index and r_index) then the duty factor is set to -1 and the period is set to 
the width of the pulse (distance between the rising and falling mesial 
points). 

pls_calc operates only on the first dimension and the first tuple of the input 
waveform, wave. If wave represents multiple pulses, the time-related 
parameters will represent the first pulse. 
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A FATAL error is issued if any of the following criteria are not met: 


wave must be a valid waveform. 
/ index must be less than r_index. 
Both / index and r_index must be within bounds of waveform wave. 
top must not equal bottom. 

A WARNing error is issued if any of the following criteria are not met: 
dir should be either RIGHT or LEFT. If it is not, it is set to RIGHT. 
n should be at least 1. If it is not, it is set to 1. 


eoaa should be EA REPEAT, EA BOUNCE, EA INVERT, 
EA WRAP, or EA ZERO. If it is not, it is set to EA REPEAT. See 
page 8-2 for an explanation of these values. 


The values in tlevel should be consistent. If they are not, the default 
values of 0.1, 0.5 and 0.9 are used. 


This function returns an error code (as defined in the spd.h include file) 
indicating whether it was able to execute correctly. 


SEE ALSO 
Include files: 
spd.h 
wav.h 
sp.h 
Signal processing library function: 
cross 


BASIC FORMAT 


CALL bplscalc( wavez, lindex&, rindex&, dir%, top#, bottom#, n%Z, 
eoaaZ, tlevel#(0), params#(0), statusZ ) 


Where: 


wave%: 
integer identifying the waveform containing data to be examined. 


lindex&: 
leftmost index in wave to be examined. 
rindex&: 
rightmost index in wave to be examined. 
dirZo: 
direction of search. 
0 for left 
1 for right 
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top#: 
value of predetermined high level of the signal. 


bottom#: 
© value of predetermined low level of the signal. 
nZ% 


number of elements that must stay crossed for the crossing to be valid. 


eoaa%: 
end-of-array algorithm. Should be one of the pre-defined constants 
REPEAT%, BOUNCE%, INVERT%, WRAP%, or ZERO%. See page 8- 
2 for an explanation of these values. 


tlevel#(0): 
integer identifying a three-element double array containing the percent- 
age levels for the proximal, mesial, and distal points. 

params# (0): 
integer identifying an eleven-element double array in which the calcu- 
lated parameters are returned. See the "C" language description above 
for details. 


status To: 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
pls_dutyf 
PURPOSE 


Calculates the duty factor of a pulse, using the information between two in- 
dices into a given waveform array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
pls_dutyf(wave, l_index, r_index, dir, num_samples, dutyf) 


WAVEFORM *wave; 

long l_index, r_index; 
int dir, num_samples; 
double *dutyf; 


Where: 


wave. 
pointer to the input waveform. 
I index: 
index of the leftmost waveform array element to be considered. 
r_ index: 
index of the rightmost waveform array element to be considered. 
dir: 
direction of search (RIGHT or LEFT). 
num_samples: 
number of waveform array samples that must remain all above or below 
the level determined by the average of the minimum and maximum 


data values between waveform indices / index and r_ index in order for a 
“cross point" (described below) to be valid. 


dutyf: 
duty factor of the waveform to be returned to the calling function. 


DESCRIPTION 


pls_dutyf calculates the duty factor of a waveform, using the waveform array 
data between indices / index and r_ index. 


First, the average of the minimum and maximum data values between the 
two indices is determined. Then, by scanning from element / index (if dir 
equals RIGHT) or r_index (if dir equals LEFT), the waveform array is sear- 
ched for three valid "cross points" specified as fractional array index values 
at which the interpolated value of the waveform intersects the average 
value of the minimum and maximum data values. By examining the mag- 
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nitudes of the data values at array index locations to either side of the mid- 

dle “cross point,” the region of the waveform (between cross points 1 and 2 

or 2 and 3) where data values are greater than the average of the minimum 
& and maximum data values can be determined. The duty factor is then the 

fractional number of array index locations spanned by the above region 
divided by the period of the waveform (which is the absolute value of the 
difference between the fractional index values of the first and third cross 
points). 


To ensure that end-of-array effects are not encountered, / index and 

r index should be 7 or more array locations from the beginning and end of 
the waveform array, respectively. This is because six points to either side of 
a "cross point” are used in the interpolation. 


The input waveform must be valid. /_ index must be _ than r_index and 
both must be within the waveform array bounds. num _samples should be 
greater than or equal to one and dir should be LEFT or RIGHT (see the 
sp.h include file). 


If the waveform array data is insufficient to determine the duty factor, dutyf 
is set to -1. If the waveform data is sufficient to determine the duty factor 
but one or more of the "cross points” needed to calculate the duty factor is 
outside the specified range, the duty factor is calculated and an out-of- 
range WARNing error is issued. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 

SEE ALSO 
Include files: 


spd.h 
wav.h 
sp.h 
Signal processing library function: 


cross 
BASIC FORMAT 


CALL bplsduty( wavez, lindex&, rindex&, dir%, numsamplesZ, 
dutyf#, statusZ ) 


Where: 
wave Zo 
integer identifying the input waveform. 


lindex&: 
index of the leftmost waveform array element to be considered. 
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rindex&: 
index of the rightmost waveform array element to be considered. 
dir%: 
direction of search. 
0 for left 
1 for right 


numsamples%: 


array samples that must remain all above or below the level determined 
by the average of the minimum and maximum data values between 
waveform indices / index and r_index in order for a "cross point" 
(described above) to be valid. 


dutyf#: 
duty factor of the waveform to be returned to the calling function. 


statusTo: 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
pls edge 


PURPOSE 


Locates the points (indexes) at which the 50% transition levels occur on the 
leading and trailing edges of a pulse. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
pls_edge(wave, 1 index, r_index, dir, n, eoaa, lead, trail, lead2) 


WAVEFORM *wave; 

long l_index, r_index; 

int dir, n, eoaa; 

long *lead, “trail, *lead2; 


Where: 


wave: 

pointer to waveform containing data to be examined 
I index: 

leftmost index in wave to search for pulse edges 


r_ index: 
rightmost index in wave to search for pulse edges 

dir: 
search direction —- RIGHT (from / index toward r_ index) or LEFT 
(from r_index toward | index) 


minimum number of consecutive elements that must lie beyond a 50% 
level crossing for that crossing to be valid 


eo0aa: 
end-of-array algorithm to use 
lead: 
pointer to the variable in which the index just past the 50% point in the 
' rising edge will be returned 
trail: 
_ pointer to the variable in which the index just past the 50% point in the 
falling edge will be returned 


lead2: 
pointer to the variable in which the index just past the 50% point in the 
second rising edge will be returned 
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DESCRIPTION 


pls_edge determines the transition 50% level as the average between the 
highest and lowest values in the waveform interval specified. Then, using 
the specified search direction, the transition 50% levels for the pulse edges 
are found and stored in the output variables, lead, trail and lead2. The 
order and number of edges stored is dependent on the search direction, the 
number of non-NIL output variables and the number of edges in the pulse 
waveform. 

If dir equals RIGHT then the fill order is from lead, trail to lead2. Search- 
ing continues until all non-NIL output variables have been filled. For ex- 
ample, if lead2 is NIL then searching stops after the first two edges have 
been found. If trai/ is NIL then the first transition is stored in /ead, the 
second transition is ignored and the third transition is stored in /ead2. 


If dir is LEFT the fill order is reversed from the above case. If lead2 is non- 
NIL then the first transition is stored in /ead2, the second transition stored 
in trail (if non-NIL) and the third transition is stored in /ead (if non-NIL). 
If lead2 is NIL then the first transition is ignored. Searching is discon- 
tinued as soon as all non-NIL variables are loaded with information. 


If relevant edges are not found in the waveform, then the unfilled output 
variables are set to -1. 


When a point that is beyond the 50% transition level is found, the next n - 1 
samples are checked to be sure that they, also, lie beyond the transition 
50% level. If the crossing point is an integral index, the point before the 
crossing is checked to ensure that it is below the transition 50% level. If this 
requires an index outside the waveform bounds, eoaa is used to determine 
the value of the element. 


NOTE 


€oaa is only used to determine if a potential pulse transition that 
occurs near the end of the waveform is valid. It is not used to con- 
tinue the search for new pulse transitions. 


Data is taken from the first tuple and the first dimension of the waveform. 
If any of the following criteria are not met, a FATAL error is issued: 

wave must be a valid waveform. 

/ index must be less than r_index. 

Both /_ index and r_index must be within bounds of waveform, wave. 
If any of the following criteria are not met, a WARNING error is issued: 

n should be at least 1. If it is not, it is set to 1. 


8-118 Signal Processing & Display 


Signal Processing 
pls edge 


eoaa should be one of EA REPEAT, EA BOUNCE, EA INVERT, 
EA _ WRAP, and EA _ ZERO. (See page 8-2 for an explanation of 
these values. ) 
If it is not, it is set to EA REPEAT. See page 8-2 for a description of these 
arguments. 


An error code is returned indicating whether pls_edge was able to execute 
correctly. As long as no other errors are encountered, a NOERROR error 
code is returned even if one or both of the edges could not be determined. 
If end-of-array effects are used in any manner by the routine, a WARNing 
error code is returned and an error message is output. For more informa- 
tion regarding the error code returned, consult the spd.h include file. 


SEE ALSO 
Include files: 


spd.h 
wav.h 


sp.h 
BASIC FORMAT 


CALL bplsedge( wavez, lindex&, rindex&, dirZ, nZ, eoaaz, lead&, 
trail&, lead2&, statusZ ) 


Where: 


wave J: 
integer identifying the waveform containing data to be examined. 
lindex&: 
leftmost index in wave to search for pulse edges. 
rindex&: 
rightmost index in wave to search for pulse edges. 
dirZo: 
direction of search. 
0 for left 
1 for right 


n%: 
minimum number of consecutive elements that must lie beyond a 50% 
level crossing for that crossing to be valid. 


eoaa%: 
end of array algorithm. Should be one of the pre-defined constants 
REPEAT%, BOUNCE%, INVERT%, WRAP%, or ZERO%. See page 8- 
2 for an explanation of these values. 

lead&: 
variable in which the index just past the 50% point in the rising edge 
will be returned. 
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trail&: 
variable in which the index just past the 50% point in the falling edge 
will be returned. 


lead 2&: _ 
variable in which the index just past the 50% point in the second rising 
edge will be returned. 


status % 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
pls ftime 


PURPOSE 


Determines falltime and falling distal, mesial, and proximal points for a 
given waveform. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
pls_ftime(wave, 1 index, r_index, dir, top, bottom, n, eoaa, 
tlevel, arr) 


WAVEFORM *wave; 

long l_index, r_index; 
int dir; 

double top, bottom; 
int n, eoaa; 

double *tlevel, “arr; 


Where: 
wave: 

pointer to waveform containing data to be examined. 
l index: 

index of leftmost element in pulse epoch being examined. 
r_index: 

index of rightmost element in pulse epoch being examined. 
dir. 

direction of search (RIGHT or LEFT). 
top: 

high state of waveform. 


bottom: 
low state of waveform. 


number of samples that have to stay crossed for a crossing to be valid. 
Used in SPD function cross(). 


eoaa: 
end-of-array algorithm to use if needed in SPD function cross(). 


tlevel: 
pointer to three-element array containing the fractional levels for the 
proximal, mesial, and distal points. 
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arr: 
pointer to four-element array in which to store falltime, distal point, 
mesial point, and proximal point. 


DESCRIPTION 


pls_ftime calls the SPD function cross() four times to determine the follow- 
ing parameters for the pulse in wave: 


arr{[0] = falltime 

arr{1] = falling distal point 
arr[2] = falling mesial point 
arr[3]_ = falling proximal point 


The first three elements pointed to by t/evel should contain the fractional 
levels for calculating the proximal, mesial, and distal points, respectively. If 
the contents of those three elements are not consistent (0 < = tlevel[0] < 
tlevel[1] < tlevel[2] < = 1), default levels are used: 


proximal - .10 (10%) 
mesial -.50 (50%) 
distal -.90 (90%) 


The level for the points is determined by adding the appropriate fraction 
times top - bottom to bottom. 


The calls to cross depend on dir. 


If dir = RIGHT, pls _ftime first calls cross to find the first distal point. From 
there it searches for the next proximal point, and once that is found, sear- 
ches LEFT from the proximal point to find the appropriate distal point. 
(This may or may not be the same point as was found on the first search.) 
From this point, searching to the RIGHT, pis_ftime calls cross to find the 
mesial point. The falltime is calculated as the proximal point minus the dis- 
tal point, and the information found is stored in the appropriate array ele- 
ments. 


If dir = LEFT, pls_ftime first calls cross to find the first proximal point. 
From there it searches for the next distal point, and once that is found, sear- 
ches RIGHT from the distal point to find the appropriate proximal point. 
(This may or may not be the same point as was found on the first search.) 
From this point, searching to the LEFT, pls_ftime calls cross to find the 
mesial point. The falltime is calculated as the proximal point minus the dis- 
tal point, and the information found is stored in the appropriate array ele- 
ments. 


Data is taken from the first dimension and first tuple of the input 
waveform. The waveform must be valid. /_ index must be less than r_ index 
and both must be within the waveform bounds. If dir is not RIGHT or 
LEFT, a warning error is issued and dir is set to RIGHT. » should be at 
least 1. If it is not, a WARNing error is issued and it is set to 1. eoaa should 
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be one of EA REPEAT, EA BOUNCE, EA INVERT, EA WRAP, and 
EA ZERO. See page 8-2 for a description of these arguments. If it is not, 

a WARNing error is issued and it is set to EA REPEAT. The data 
returned may not be meaningful if the waveform interval specified does not 
represent pulses that have exactly two discernible states or if top or bottom 
are not correctly specified. 

An error code is returned indicating whether or not pls_ftime was able to ex- 
ecute correctly. A FATAL error code is returned if none of the 4 
parameters could be determined. For more information regarding the error 
code returned, consult the spd.h include file. 


SEE ALSO 
Include files: 
spd.h 
sp.h 
wav.h 
Signal processing library function: 
Cross 


BASIC FORMAT 


CALL bplsftime( waveZ, lindex&, rindex&, dirZ, top#, bottom#, nZ, 
eoaaz, tlevel#(0), arr#(0), statusZ ) 


Where: 


wave %: 

integer identifying the waveform containing data to be examined. 
lindex&: 

index of leftmost element in pulse epoch being examined. 
rindex&: 

index of rightmost element in pulse epoch being examined. 
dir%: 


direction of search. 


0 for left 
1 for right 
top#: 
high state of waveform. 


bottom#: 
low state of waveform. 


n%: 
number of samples that have to stay crossed for a crossing to be valid. 
Used in SPD function cross(). 
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eoaa%: 
end of array algorithm. Should be one of the pre-defined constants 
REPEAT%, BOUNCE%, INVERT%, WRAP%, or ZERO%. See page 8- 
2 for an explanation of these values. | 

tlevel# (0): 
three-element array containing the fractional levels for the proximal, 
mesial, and distal points. 

arr# (0): 
four-element array in which to store falltime, distal point, mesial point, 
and proximal point. 

status To 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
pls_hist 


PURPOSE 


Calculates top and bottom values for a pulse, using a histogram method. 
SYNOPSIS 
#include “tekspd.h" 


ERRORTYPE 
pls_hist(wave, l_index, r_index, hist, n_bins, top, bottom) 


WAVEFORM *wave; 

long l_index, r_index; 
int hist, n_bins; 
double *top, *bottom; 


Where: 


wave: 
pointer to waveform containing data to be examined. 


1 index: 
index of first element in pulse epoch being examined. 
r_index: 
index of last element in pulse epoch being examined. 
hist: 
MODE or MEAN — whether to use the peaks or the means in the 
binodal histogram to determine the high and low levels. 
n_bins: 
number of bins to use for histogram. This should be greater than or 
equal to three. 
top: 
address in which to store amplitude of high state. 


bottom: 
address in which to store amplitude of low state. 


DESCRIPTION 


pls_hist takes data from wave between the indices /_ index and r_index, 
makes a histogram of the points in the pulse and determines the high and 
low levels from it. First, the minimum and maximum levels in the interval 
specified are found. Then, the difference is divided by (”_bins - 1) to get 
the range of amplitudes per element in the histogram. For each point in the 
waveform, the appropriate element in the histogram array is incremented. 
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The histogram array should have two nodes, one representing the high state 
and one representing the low state. The high and low states can be deter- 


mined one of two ways: 
If hist is MODE, the high and low levels are the values represented by © 
the peaks of the nodes of the binodal histogram. 


If hist is MEAN, the high and low points are the values represented by 
the means of the nodes of the binodal histogram. 


The waveform must be valid. Data is taken from the first tuple and the first 
dimension of the waveform. / index must be less than r_index and both 
must be within the waveform bounds. If hist is not MODE or MEAN, a 
WARNing error is issued and MODE is assumed. 

This functions returns an error code (as defined in the spd.h include file) 
indicating whether or not it was able to execute correctly. 


SEE ALSO 
Include files: 


BASIC FORMAT © 


CALL bplshist( wave%, lindex&, rindex&, hist%Z, nbins%, top#, bot- 
tom#, statusZ ) 


Where: 


wave Jo: 
integer identifying the waveform containing data to be examined. 
lindex&: 
index of first element in pulse epoch being examined. 
rindex&: 
index of last element in pulse epoch being examined. 
hist%: 
integer indicating whether to use the peaks or the means in the binodal 
histogram to determine the high and low levels. 


0 for peak 
1 for mean 


nbins%: 
number of bins to use for histogram. This should be greater than or @ 
equal to three. 


top#: 
variable in which to store amplitude of high state. 


8-126 Signal Processing & Display 


Signal Processing 


pls_hist 
bottom#: 
variable in which to store amplitude of low state. 
status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
pls_meas 


PURPOSE ©& 


Calculates parameters describing a pulse between two indices in a given 
waveform. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
pls_meas(wave, l_index, r_index, dir, hist, n, eoaa, tlevel, 
params ) 


WAVEFORM *wave; 

long l_index, r_index; 
int dir, hist, n, eoaa; 
double *tlevel, “params; 


Where: 


wave: 
pointer to waveform containing data to be examined. ®@ 


1 index: 


index of first element in pulse interval being examined. 
r index: 
index of last element in pulse interval being examined. 
dir. 
direction of search (RIGHT or LEFT). 
Aist: 
MODE or MEAN - whether to use the peaks or the means in the 
bimodal histogram to determine the high and low levels. 


n: 
number of elements that must stay crossed for a crossing to be valid. 
eoaa: 
end-of-array algorithm to use if needed. 
tlevel: 
pointer to a three-element double array containing the fractional levels 
for the proximal, mesial, and distal points. 
params: 
pointer to an eleven-element double array in which the calculated 


parameters are returned. 
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DESCRIPTION 


pls_meas takes data from wave between the indices /_index and r_index, 
makes a histogram of the levels in the first period in the pulse, and deter- 
mines the high and low levels from it. 


If hist is MODE, the high and low levels are, respectively, the two 
peaks of the histogram; i.e., the most frequent high level and the most 
frequent low level. 


If hist is MEAN, the high and low levels are, respectively, the local 
means of the two nodes of the histogram. 


If Aist is neither MEAN nor MODE, MODE is assumed. 


The parameters are then calculated and stored in the array pointed to by 
params such that: 


params[0] = pulse amplitude 


params[1] = misetime 

params[2] = rising proximal point 
params[3] = rising mesial point 
params[4] = rising distal point 
params[5] = falltime 


params[6] = falling distal point 
params[7] = falling mesial point 
params[8] = falling proximal point 
params[9] = duty factor (fractional) or -1 
params[10] = period or pulse width 


The first three elements pointed to by tlevel should contain the fractional 
levels for calculating the proximal, mesial, and distal points, in that order. If 
the contents of those three elements are not values such that 0 < ¢tlevel/0] 
< tlevel[1] < tlevel[2] < = 1, the following default levels are used: 


proximal: 10 (10%) 
mesial: 50 (50%) 
distal: 90 (90%) 


Risetime is the number of waveform samples between the proximal and distal 
points on the rising edge. Falltime is the number of waveform samples between 
the distal and proximal points on the falling edge. The period is the number of 
waveform samples between mesial points on successive rising or falling transi- 
tions. The duty factor is the ratio of the number of waveform samples during 
which the amplitude is above the mesial point to the period. 


If the pulse waveform is not periodic (i.e., fewer than three edges between 
! index and r_ index) then the duty factor is set to -1 and the period is set to the 
width of the pulse (distance between the rising and falling mesial points). 
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pls_meas operates only on the first dimension and the first tuple of the 
input waveform, wave. The data returned may not be meaningful if the 
waveform interval specified does not represent pulses that have exactly two 
discernible states. 


A FATAL error is issued if any of the following criteria are not met: 

wave must be a valid waveform. 
! index must be less than r_index. 
Both / index and r_index must be within bounds of waveform wave. 

A WARNing error is issued if any of the following criteria are not met: 
dir should be either RIGHT or LEFT. If it is not, it is set to RIGHT. 
hist should be either MODE or MEAN. If it is not, it is set to MODE. 
n should be at least 1. If it is not, it is set to 1. 


eoaa should be EA REPEAT, EA BOUNCE, EA INVERT, 
EA WRAP, or EA_ ZERO. If it is not, it is set to EA_ REPEAT. See 
page 8-2 for a description of this argument. 


The values in t/evel should be consistent. If they are not, the first three 
elements of tlevel are overwritten by the default values. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 

SEE ALSO 
Include files: 


spd.h 
wav.h 
sp.h 
Signal processing library functions: 
pls_hist 
pls_calc 
BASIC FORMAT 


CALL bplsmeas( wave%z, lindex&, rindex&, dir%z, histZ, nZ, eoaaZ, 
tlevel#(0), params#(0), statusZ ) 


Where: 
wave Zo: 
integer identifying the waveform containing data to be examined. 
lindex&: 
index of first element in pulse interval being examined. 
rindex&: 
index of last element in pulse interval being examined. 
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dir%: 
direction of search. 


0 for left 


© 1 for right 
hist%: 


integer indicating whether to use the peaks or the means in the bimodal 
histogram to determine the high and low levels. 


n%: 
number of elements that must stay crossed for a crossing to be valid. 


eoaa%: 
end of array algorithm. Should be one of the pre-defined constants 
REPEAT%, BOUNCE%, INVERT%, WRAP%, or ZERO%. See page 8- 
2 for an explanation of these values. 


tlevel# (0): | 
three-element double array containing the fractional levels for the 
proximal, mesial, and distal points. 

params# (0): 
eleven-element double array in which the calculated parameters are 
returned. See the "C” language description above for details. 


status [% 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
pls_negpk 


PURPOSE 
Determines the location and value of the maximum negative pulse peak. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
pls_negpk(wave, l_index, r_index, pkloc, pkval) 


WAVEFORM *wave; 
long l_index, r_index; 
double *pkloc, *pkval; 


Where: 


wave: 
pointer to waveform containing data to be examined. 


I index: 

index of leftmost element in waveform being examined. 
r index: 

index of rightmost element in waveform being examined. 


pkloc: 
address in which to store the location of the peak value. 


pkval: 
address in which to store the peak value. 


DESCRIPTION 


pls_negpk finds the highest negative peak in the waveform between /_ index 
and r_index. A negative peak is defined as a location in a waveform where 
the adjacent locations have values greater than the peak. Determining the 
negative peak value is accomplished in two steps. First, the neighborhood 
of the peak is determined by fitting a parabola to any potential peak loca- 
tion. This procedure searches out the maximum negative peaks in a 
waveform even though they may not lie on a sampled data point. Once the 
neighborhood of the peak is found, then single point interpolation is used 
iteratively to find the true peak value. 


The method of interpolation used works well for determining the negative- 
going overshoot of a step waveform. If the high and low amplitude values 
are known and this routine is called, the overshoot can be computed as fol- 
lows: 


overshoor = pha! — bottom 
‘ ttom — top 


8-132 Signal Processing & Display 


Signal Processing 
pls_negpk 


Accuracies for measuring overshoot will typically produce results that are 
within 0.1% of the true overshoot value. 


If a waveform peak is not found between /_ index and r_index, pkloc is set to 
6 -1 and pkval is set to 0. 


The waveform must be valid. Only the first tuple of the first dimension in 
the waveform is used. / index must be less than r_index and both must be 
within the waveform bounds. 


If the peak lies too close to the edge of the waveform, the end value of the 
waveform is repeatedly used to compute the peak value. A WARNing error 
is issued to indicate the potential loss of accuracy. To insure that no error 1s 
issued, there must be at least 6 samples between the peak and either end of 
the waveform. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 

SEE ALSO 
Include files: 


wav.h 
spd.h 


© BASIC FORMAT 
CALL bplsnegp( wave%, lindex&, rindex&, pkloc#, pkval#, status% ) 
Where: | 


wave J: 

integer identifying the waveform containing data to be examined. 
lindex&: 

index of leftmost element in waveform being examined. 
nindex&: 

index of rightmost element in waveform being examined. 


pkloc#: 
integer indicating the location of the peak value. 


pkval#: 
peak value. 
status To 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 


pls pamp 
PURPOSE ®@ 


This function measures the amplitude of a periodic rectangular pulse at the 
centers between pulse transitions. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
pls_pamp (wave, l_index, r_index, dir, n_av, n, eoaa, top, bottom) 


WAVEFORM *wave; 

long l_index, r_index; 
int dir, n_av, n, eoaa; 
double *top, *bottom; 


Where: 


wave: 
pointer to waveform containing data to be examined 


I index: 
leftmost index in wave to search for pulse 


r_ index: 
rightmost index in wave to search for pulse 

dir: 
the direction of search - RIGHT (from / index to r_ index) or LEFT 
(from r_index to/ index) 


mM av: 


~ number of elements around the centers of the pulse to compute the top 
and bottom pulse levels 


n: 
number of consecutive samples that must be beyond the transition 50% 
level for the transition to be valid (used in pls_edge()) 
eoaa: 
end-of-array algorithm to use in case computations require data from 
outside the waveform bounds 
top: 
pointer to variable in which the pulse top amplitude is returned @ 
bottom: 


pointer to a variable in which the pulse bottom amplitude is returned 
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DESCRIPTION 


pls_pamp first calls pls_edge() to find the approximate locations of the three 
pulse transitions necessary to determine a period of the pulse. The center 
locations between the first and second transitions, and the second and third 
transitions are found. The »_av points around each of these locations are 
used to calculate the pulse top and bottom values. The pulse top value out- 
put is the largest of the two computed levels and the pulse bottom value is 
the smallest level. 


A fatal error is issued if any of the following criteria are not met: 
wave must be a valid waveform. 
! index must be less than r_index. 
[ index and r_ index must be within bounds of waveform wave. 
Three waveform transitions must be found in wave. 

A warning error is issued if any of the following criteria are not met: 
n should be at least 1. If it is not, it is set to 1. 
n_av should be at least 1. If it is not, it is set to 1. 


eoaa should be EA REPEAT, EA BOUNCE, EA INVERT, 
EA WRAP, or EA ZERO. If it is not, it is set to EA REPEAT. See 
page 8-2 for a description of this argument. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 

SEE ALSO 
Include files: 


spd.h 
wav.h 


sp.h 
Signal processing functions: 
pls_amp 
pls edge 
BASIC FORMAT 


CALL bplspamp( waveZ, lindex&, rindex&, dirZ, navZ, n%, eoaaz, 
top#, bottom, status2Z ) 


Where: 


wave % 
integer identifying the waveform containing data to be examined. 


lindex& 
leftmost index in wave to search for pulse. 
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rindex& 

rightmost index in wave to search for pulse. 
dir% 

the direction of search. 
nav% 


number of elements around the centers of the pulse to compute the top 
and bottom pulse levels. 


nZ 
number of consecutive samples that must be beyond the transition 50% 
level for the transition to be valid (used in pls _edge()). 


eoaaYo 
end-of-array algorithm to use in case computations require data from 
outside the waveform bounds. Should be one of the pre-defined con- 
stants REPEAT%, BOUNCE%, INVERT%, WRAP%, or ZERO%. See 
page 8-2 for an explanation of these values. 


lop# | 
variable in which the pulse top amplitude is returned. 


bottom # 
variable in which the pulse bottom amplitude is returned. 


status7%o 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
pls_ period 
PURPOSE 


Calculates the period of a pulse in a specified range of a given waveform 
array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTY PE 
pls_period(wave, l_index, r_index, dir, num_samples, period) 


WAVEFORM *wave; 

long l_index, r_index; 
int dir, num_samples; 
double *period; 


Where: 


wave: 
pointer to the input waveform . 

I index: 
index of the leftmost waveform array element to be considered. 


r_index: 
index of the rightmost waveform array element to be considered. 

dir: 
direction of search (RIGHT or LEFT). 

num_samples: 
number of waveform array samples that must remain all above or below 
the level determined by the average of the minimum and maximum 
data values between waveform indices / index and r_index in order for a 
“cross point” (described below) to be valid. 

penod: 

period of the waveform to be returned to the calling function. 


DESCRIPTION 


pls_period calculates the period of a waveform using, the waveform array 
data between indices / index andr index. _ 


two indices is determined. Then, by scanning from element / index (if dir 
equals RIGHT) or r_index (if dir equals LEFT), the waveform array is sear- 
ched for three valid "cross points" specified as fractional array index values 
at which the interpolated value of the waveform intersects the average 
value of the minimum and maximum data values. The first and the third 


& First, the average of the minimum and maximum data values between the 


Signal Processing & Display 8-137 


Signal Processing 
pls period 


valid points of intersection yield the period of the waveform returned as the 
absolute value of the difference between the fractional index values of the 
two cross points. 


To ensure that end-of-array effects are not encountered, / index and © 
r_index should be 7 or more array locations from the beginning and end of 

the waveform array respectively. This is because six points to either side of 

a "cross point" are used in the interpolation. 


The input waveform must be valid. /_index must be less than r_index and 
both must be within the waveform array bounds. num_samples should be 
greater than or equal to one and dir should be LEFT or RIGHT (see the 
sp.h include file). 

If the waveform array data is insufficient to determine the period, period is 
set to-1. If the waveform data is sufficient to determine the period but one 
or more of the "cross points" needed to calculate the period is outside the 
specified range, the period is calculated and an out-of-range WARNing 
error is issued. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 


SEE ALSO 


Include files: @ 
.wav.h 
spd.h 
sp.h 

Signal processing library function: 


Cross 
BASIC FORMAT 


CALL bplsperiod( wavez, lindex&, rindex&, dir%, numsamplesZ, 
period#, statusZ ) 


Where: 
wave Jo: 

integer identifying the input waveform. 
lindex&: 

index of the leftmost waveform array element to be considered. 
rindex&: 

index of the rightmost waveform array element to be considered. @ 
dir%: 
direction of search. 


0 for left 
1 for right 
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numsamples%: 
number of waveform array samples that must remain all above or below 
the level determined by the average of the minimum and maximum 
data values between waveform indices lindex and rindex in order for a 
© "cross point” to be valid. 


period#: 
period of the waveform to be returned to the calling function. 
status % 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
pls pkfind 


PURPOSE 


Locates the peak of the first positive-going or negative-going pulse within a 
specified interval in a waveform and calculates the amplitude of the peak. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 

pls_pkfind(wave, l_index, r_index, dir, rel_amp, fract, eoaa, 
pk_loc, pk_amp) 

WAVEFORM *wave; 

long l_index, r_index; 

double rel_amp, fract; 


int dir, eoaa; 
double *pk_loc, *pk_amp; 


Where: 


wave: 
pointer to waveform containing data to be examined. 6 
I index: 
leftmost index in wave to search for peak. 
r_index: 
rightmost index in wave to search for peak. 
dir: 
direction in which to scan waveform for first peak: LEFT (right to left) 
or RIGHT (left to right). 
rel_amp: 
minimum peak amplitude relative to the first element in wave in the 
search. 


fract: 
fraction of rel_amp that has to be reached by the falling edge of a pulse 
for the pulse to be considered valid. 


eoaa: 
end-of-array algorithm to use if needed. 


pk_loc: 
address in which to store the fractional index of the first peak of the © 
pulse in wave. 


pk_amp: 
address in which to store the amplitude of the first peak of the pulse. 
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DESCRIPTION 


pls_pkfind defines ref as the value of the first element in the search (/_ index 

if dir = RIGHT and r index if dir = LEFT). Two consecutive points are 
@ found with amplitudes greater than or equal to rel_amp + ref. The index 

returned is the starting index to search for a peak. pls pkfind determines an 
index for the end of the search by locating two consecutive points below 
rel_amp « fract + ref. If the first index is not found, a FATAL error is 
returned to the user. If the second index is not found, a WARNing error 
message is issued and the last index in the interval specified by the user is 
used as an ending index. 


pls_pkfind searches the interval just determined for the highest peak that 
has two rising points before it and two falling points after it. (If a negative 
rel_amp is specified, the points before it are falling and those after are 
rising.) Once a local maximum is determined, a parabola is calculated to 
pass through this maximum and two points to either side of it. The maxi- 
mum of this parabola is taken as the true maximum value, and is stored in 
the address specified by pk_amp. The fractional index at which it occurs is 
stored in the address specified by pk_loc. 


If no valid peak is found, -1 is stored in the address specified by pk _loc and 
the reference level (r_index or !_index, depending on dir) is stored in the ad- 
dress specified by pk_amp. If the peak value lies at one edge of the 
waveform, end-of-array effects are used to calculate the outside point for 
use in parabola fitting. If this happens, a WARNing error is issued, alerting 
the user to possible inaccuracy. 


Data is taken from the first tuple and the first dimension of the waveform. 
The waveform must be valid. fract must be between zero and one. dir must 
be LEFT or RIGHT. If it is not, a WARNing error is issued and it is set to 
RIGHT. /_ index must be less than r_index and both must be within the 
waveform bounds. eoaa must be one of EA _ REPEAT, EA BOUNCE, 
EA _ INVERT, EA WRAP, and EA _ ZERO (see the sp.h include file). If it 
is not, a WARNing | error is issued and it is set to EA REPEAT. See page 
8-2 for an explanation of these values. 

This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 


SEE ALSO 
Include files: 
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BASIC FORMAT 


CALL bplspkfind( wave%, lindex&, rindex&, dir%, relamp#, fract#, 
eoaaz, pkloc#, pkamp#, statusZ ) 


Where: 


wave %: 
integer identifying the waveform containing data to be examined. 
lindex&: 
leftmost index in wave to search for peak. 
rindex&: 
rightmost index in wave to search for peak. 
dir%: 
direction of search. 
0 for left 
1 for right 
relamp#: 
minimum peak amplitude relative to the first element in wave in the 
search. 
fract#: 
fraction of relamp that has to be reached by the falling edge of a pulse 
for the pulse to be considered valid. 
eoaa%: 
end of array algorithm. Should be one of the pre-defined constants 
REPEAT%, BOUNCE%, INVERT%, WRAP%, or ZERO%. See page 8- 
2 for an explanation of these values. 
pkloc#: 
fractional index of the first peak of the pulse in wave. 
pkamp#: 
amplitude of the first peak of the pulse. 
statusY 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
pls_pospk 
PURPOSE 


Determines the location and value of the maximum positive pulse peak. 


SYNOPSIS 
#include "“tekspd.h" 


ERRORTYPE 
pls_pospk(wave, l_index, r_index, pkloc, pkval) 


WAVEFORM *wave; 
long l_index, r_index; 
double *pkloc, *pkval; 


Where: 


wave: 

pointer to waveform containing data to be examined. 
1 index: 

index of leftmost element in waveform being examined. 
r_index: 

index of rightmost element in waveform being examined. 


pkloc: 
address in which to store the location of the peak value. 


pkval: 
address in which to store the peak value. 


DESCRIPTION 


pls_pospk finds the highest positive peak in the waveform between / index 
and r_index. A peak is defined as a location in a waveform where the ad- 
jacent locations have values less than the peak. Determining the peak value 
is accomplished in two steps. First, the neighborhood of the peak is deter- 
mined by fitting a parabola to any potential peak location. This procedure 
searches out the maximum peaks in a waveform even though they may not 
lie on a sampled data point. Once the neighborhood of the peak is found, 
then single point interpolation is used iteratively to find the true peak value. 


The method of interpolation used works well for determining the overshoot 
of a step waveform. If the high and low amplitude values are known and 
this routine is called, then the overshoot can be computed as follows: 


= pkval — top 
overshoot lop — botlom 
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Accuracies for measuring overshoot will typically produce results that are 
within 0.1% of the true overshoot value. 


If a waveform peak is not found between / index and r_index, then pkloc is 


set to -1 and pkval is set to 0. ® 
The waveform must be valid. Only the first tuple of the first dimension is 

used. / index must be less than r_index and both must be within the 

waveform bounds. | 

If the peak lies too close to the edge of the waveform, the end value of the 

waveform is repeatedly used to compute the peak. A WARNing error is is- 

sued to indicate the potential loss of accuracy. To insure that no error is is- 

sued there must be at least 6 samples between the actual peak and either 

end of the waveform. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 


SEE ALSO 
Include files: 


spd.h 
wav.h 


BASIC FORMAT r 
CALL bplspospk( wave%, lindex&, rindex&, pkloc#, pkval#, statusZ ) 
Where: 


wave%: 

integer identifying the waveform containing data to be examined. 
lindex&: 

index of leftmost element in waveform being examined. 
rindex&: 

index of rightmost element in waveform being examined. 
pkloc#: 

integer indicating the location of the peak value. 
pkval#: 

peak value. 
status Zo 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. & 
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NAME 
pls rtime 


PURPOSE 


Determines risetime and rising proximal, mesial, and distal points for a 
given waveform. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
pls_rtime(wave, l_index, r_index, dir, top, bottom, n, eoaa, 
tlevel, arr) 


WAVEFORM *wave; 

long l_index, r_index; 
int dir; 

double top, bottom; 
int n, eoaa; 

double *tlevel, “arr; 


Where: 


wave: 
pointer to waveform containing data to be examined. 


I index: 

index of leftmost element in pulse epoch being examined. 
r_index: 

index of rightmost element in pulse epoch being examined. 
dir: 

direction of search (RIGHT or LEFT). 


top: 
high state of waveform. 


bottom: 
low state of waveform. 


number of samples that have to stay crossed for a crossing to be valid. 
Used in SPD function cross(). 


eoaa: 
end-of-array algorithm to use if needed in SPD function cross(). 


tlevel: 
@ pointer to three-element array containing the fractional levels for the 
proximal, mesial, and distal points. 
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arr: 
Pointer to four-element array in which to store risetime, proximal point, 
mesial point, and distal point. 


DECRIPTION 


pls _rtime calls the SPD function cross() four times to determine the follow- 
ing parameters for the pulse in wave: 


arr(0] = risetime 

arr{1] = rising proximal point 
arr(2] = rising mesial point 
arr[3] = rising distal point 


The first three elements pointed to by t/evel should contain the fractional 
levels for calculating the proximal, mesial, and distal points, respectively. If 
the contents of those three elements are not consistent (0 < = tlevel[0] < 
tlevel[1] < tlevel[2] < = 1), default levels are used: 


proximal - .10 (10%) 
mesial -.50 (50%) 
distal -.90 (90%) 


The level for the points is determined by adding the appropriate fraction 
times top - bottom to bottom. The calls to cross depend on dir: 


If dir = RIGHT, pls_rtime first calls cross to find the first proximal point. 
From there it searches for the next distal point, and once that is found, sear- 
ches LEFT from the distal point to find the appropriate proximal point. 
(This may or may not be the same point as was found on the first search.) 
From this point, searching to the RIGHT, pls_rtime calls cross to find the 
mesial point. The risetime is calculated as the distal point minus the 
proximal point, and the information found is stored in the appropriate 

array elements. 


If dir = LEFT, pis _rtime first calls cross to find the first distal point. From 
there it searches for the next proximal point, and once that is found, sear- 
ches RIGHT from the proximal point to find the appropriate distal point. 
(This may or may not be the same point as was found on the first search.) 
From this point, searching to the LEFT, p/s_rtime calls cross to find the 
mesial point. The risetime is calculated as the distal point minus the 
proximal point, and the information found is stored in the appropriate 
array elements. 


Data is taken from the first dimension and first tuple of the input 
waveform. The waveform must be valid. /_ index must be less than r_index 
and both must be within the waveform bounds. If dir is not RIGHT or 
LEFT, a WARNing error is issued and dir is set to RIGHT.» should be at 
least 1. If it isn’t, a WARNing error is issued and it is set to 1. eoaa should 
be EA REPEAT, EA BOUNCE, EA INVERT, EA WRAP, or 

EA _ZERO (see page 8-2 for a detailed explanation.) If it isn’t, a 


. &146 Signal Processing & Display 


| Signal Processing 


pls_rtime 


WARNing error is issued and eoaa is set to EA_REPEAT. The data 
returned may not be meaningful if the waveform interval specified does not 
represent pulses that have exactly two discernible states or if top and bot- 
tom are not correctly specified. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. A FATAL error 
code is returned if none of the four parameters could be determined. 


SEE ALSO 


Include files: 


Signal processing library function: 
cross 


BASIC FORMAT 


CALL bplsrtime( waveZ, lindex&, rindex&, dir%, top#, bottom#, nZ, 
eoaaz, tlevel#(0), arr#(0), status% ) 


Where: 


wave%: 

integer identifying the waveform containing data to be examined. 
lindex&: 

index of leftmost element in pulse epoch being examined. 
rindex&: 

index of rightmost element in pulse epoch being examined. 
dir%: 

direction of search. Use the pre-defined constants RIGHT% or 

LEFT%. 
top#: 

high state of waveform. 


bottom#: 
low state of waveform. 


nJo: 
number of samples that have to stay crossed for a crossing to be valid. 
Used in SPD function cross(). 

eoaa%: 
end of array algorithm. Should be one of the pre-defined constants 
REPEAT%, BOUNCE%, INVERT%, WRAP%, or ZERO%. See page 8- 
2 for an explanation of these values. 
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tlevel# (0): 
three-element array containing the fractional levels for the proximal, 
mesial, and distal points. 


arr# (0): 
four-element array in which to store risetime, proximal point, mesial 
point, and distal point. 

status % 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 


polar 


PURPOSE 
Converts rectangular coordinates to polar coordinates. 


SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 
polar(real, im, units, unwrap, delay, mag, phase) 


WAVEFORM *real, *im; 
UNIT units; 

BOOL unwrap; 

double delay; 
WAVEFORM *mag, “phase; 


Where: 


real: 
pointer to the waveform containing x-coordinate or real number data. 


pointer to the waveform containing y-coordinate or imaginary number 
data. 


units: 
indicates whether phase should be calculated in radians, degrees, or 
grads. 
unwrap: 
Boolean that, if true, indicates that the phase data will be unwrapped. 
delay: 
specifies a linearly varying phase adjustment. 
mag: 
pointer to the output waveform containing magnitude data. 


phase: 
pointer to the output waveform containing phase data. 


DESCRIPTION 


polar converts the data in real and im into magnitude data and phase data 
to be stored in mag and phase, respectively, using the formulas below: 


© mag_—arrli] = Vreal_arrli]” + im_arrlil? 


. . 


: ite imarrlil |,» "Jars wf 
phase_arrli] arctan | mart riT|* undwrap_adjustment' -21-de/ay:i 
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where 


mag _arr[i], phase_arr[i], real_arr[i], and im_arr[i] are waveform array 

values at the index /. 
"unwrap_adjustment” is 0 if unwrap is FALSE, else it is set to +n where © 
n is the unwrapping value used to eliminate the discontinuities at the +7 
phase boundaries. 


If either of the source waveforms, real or im, is the same as a target 
waveform, that source waveform is overwritten with the output data. If the 
waveform arrays are different sizes, the target waveform arrays will only be 
valid up to the length of the shortest of these arrays. If either mag or phase 
is a NIL pointer, the data for that waveform is simply not returned. 


units is defined by one of three predefined keywords: RAD for radians, 
GRAD for grads, or DEGREE for degrees. 


If unwrap is true, the phase data, which originally falls between wm and -m, is 
unwrapped modulo 27 to eliminate the discontinuities at 7 and -7 and give 
continuous phase. 


The delay parameter causes a linearly varying phase component whose 
slope is 2mdelay to be subtracted from the phase after rectangular-to-polar 
conversion. 


Both source waveforms and at least one target waveform must be valid. 
One target waveform pointer may be NIL. Information is taken from the 

first dimension and is placed in the first dimension. The data type informa- 

tion is taken from the dirst tuple. 


The function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 

SEE ALSO 
Include files: 


wav.h 
spd.h 
sp.h 


Signal processing library function: 
rectang 


BASIC FORMAT 


CALL bpolar(realZ,imZ,units%,unwrap2Z ,delay#,magZ, phaseZ, status2Z) 


Where: | @ 


real: 
integer identifying the waveform containing x-coordinate or real num- 
ber data. 
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im%: 
integer identifying the waveform containing y-coordinate or imaginary 
number data. 


units %: 
@ indicates whether phase should be calculated in radians, degrees, or 
grads. Use the pre-defined constants GRAD%, RAD%, or DE- 
GREE%. 


unwrap %: 
Boolean that, if true, indicates that the phase data will be unwrapped. 
Use the pre-defined constants TRUE% or FALSE%. 


delay#: 
specifies a linearly varying phase adjustment. 


mag: 
integer identifying the output waveform containing magnitude data. 


phase%: 
integer identifying the output waveform containing phase data. 


status%: 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
C: 
#include "tekspd.h" 
ERRORTYPE status; 


WAVEFORM *real, “imag; /* rectangular input */ 
WAVEFORM *mag, *phase; /* polar output */ 


status = polar(real, imag ,DEGREE,TRUE,0.0,mag, phase); 


status = wf_dunits(dim_units(real,0), COPY,0,mag); 
status = wf _dunits(dim_units(real,0), COPY,0,phase) ; 


status = wf_tunits(tup_units(real,0), COPY,0,mag); 
status = wf_tunits("Deg", COPY,0,phase) ; 


dim_scale(mag,0) = dim_scale(real,0); 
dim scale(phase,0) = dim scale(real,0); 


BASIC: 


' SINCLUDE: '\tek\spd\include\tekspd.bi’ 


realZ = 1: imag% = 2 
© magz = 3: phasez= 4 


call bpolar(realZ, imag% ,DEGREEZ , TRUEZ , O#,magz,phaseZ, statusZ) 


brtupunits(realZ,0,inVunitsS,inllen%,status2Z) 
bwftunits(inVunitsS,0Z,magZ,statusZ) 
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bwftunits("Deg", 0%, phaseZ, status2Z ) 


brdimunits(realZ%,0,inHunitsS, inHlen%, statusZ) 
bwfdunits("inHunitsS, 0% ,magZ, statusZ) 


bwfdunits("“inHunitsS,0%,phase%, statusZ) © 


brdimscale(realZz,0,hsf#, status2Z) 
bwdimscale(magz,0,hsf#,status2Z) 
bwdimscale(phaseZ,0,hsf#,status2Z) 
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NAME 
pt_interp 


© PURPOSE 


Interpolates a single value of a uniformly sampled waveform at an arbitrary 
index, which need not be an integer. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
pt_interp(input, itype, p, n, eoaa, val) 


WAVEFORM *input; 
int itype, eoaa; 
double p, *val; 
unsigned n; 


Where: 


input: 
pointer to the waveform. If this is NIL, pt_interp reports a FATAL error 
and returns. 

itype: 
flag word Ss the type of interpolation. It should be either SINC 
or LAGRANG 


eoaa: 
specifies the end-of-array algorithm to be used, if necessary. 


"index" at which the interpolation is to be obtained. 


val: 
pointer to the interpolated value. 


number of waveform samples to be used for interpolation. 


DESCRIPTION 


pt_interp estimates a single waveform array value at any arbitrary index p, by 
using waveform samples whose domain contains p. This interpolation is 
done in two different ways, depending on whether itype is set to SINC or 
LAGRANGE. 


} If itype = SINC, the interpolation is provided by a windowed sinc() kernel 
(sin(x) /x type). The window used is a 25% tapered trapezoidal window 
centered on p. This window gives the best results when n > = 4, and is also 
a multiple of 4. pt_interp checks to see whether this condition on 7 is met 
when n > = 2. If not, pt_interp uses the nearest multiple of 4. 
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If itype = LAGRANGE, then the interpolation is obtained by fitting a 

Lagrange polynomial of order» to the n waveform samples whose domain 

includes p. In this case, there is no restriction on 7. 

The special case of linear interpolation is provided by pt_interp if it is called 

with itype = LAGRANGE anda = 2. 

n specifies the number of waveform samples to be used for interpolation. In 

particular, if x[k] represents the waveform samples, the n samples used in 

the case of either SINC or LAGRANGE interpolation are x[ip + 1 - n/2] 

through x[ip + n/2] inclusive, where ip represents the integer part of p. 

The accuracy of interpolation depends on the waveform, the sampling inter- 

val, the number of samples used for interpolation, and the type of inter- 

polator used. If itype is not either SINC or LAGRANGE, pt interp sets itype 
to LAGRANGE, and reports a WARNing error message. 


Default actions are taken by pt_interp if itype and/or n are invalid, and 
these are given below. 


If n < 2, the sample closest to p is returned with a WARNing error message. 


If itype = SINC, 1 should be a multiple of 4, with a minimum value of 4. If 
these conditions on” are not met, pt_interp uses a value that is the integer 
multiple of 4 closest tom and a WARNing error message is reported. 


If values outside waveform array bounds were required for interpolation, 
then pt_interp reports a WARNing error message. The end-of-array algo- 
rithm is specified by eoaa, which must be one of the constants defined and 
discussed on page 8-2. 


The function returns an error code (as defined in the spd.h include file) in- 
dicating whether it was able to execute correctly or not. 
SEE ALSO 


Include files: 


spd.h 
wav.h 
sp.h 


BASIC FORMAT 
CALL bptinterp( input%, flagz%, p#, n%, eoaaz, val#, statusZ ) 


Where: 


input[: 
integer identifying the waveform. If this is NIL, pt_interp reports a 
FATAL error and returns. 


flag%: 
flag word specifying the type of interpolation. Use one of the pre- 
defined constants SINC% or LAGRANGE%. 
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p#: 
"index" at which the interpolation is to be obtained. 
nQ: 
number of waveform samples to be used for interpolation. 
_ eoaa%: 


end-of-array algorithm. Should be one of the pre-defined constants 
REPEAT%, BOUNCE%, INVERT%, WRAP%, or ZERO%. See page 8- 
2 for an explanation of these values. 

val#: 
interpolated value. 


status % 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
randb, initbin, state _b 


PURPOSE S 


randb returns a pseudo-random binary number 0 or 1, with probability of a 
1 user-specified. 


initbin initializes randb. 
state_b returns the current state of randb. 


SYNOPSIS 


#include "tekspd.h”" 
int randb(prob) 
double prob; 


initbin(seed) 
long seed; 


long state _b() 


DESCRIPTION 


randb(prob) uses a multiplicative congruential generator to return a binary 
number 0 or 1, with probability of 1 specified by 0.0 < = prob < = 1.0. 6 


randb(prob) is initialized to a required seed by a one-time prior call to iit- 
bin(seed). In particular, the initial state of randb(prob) is set to the absolute 
value of seed if seed is odd, and to the absolute value of seed plus 1, if it is 
even. 


If randb(prob) is called directly without a prior call to the initializer func- 
tion initbin(seed), then a starting seed of 1 is assumed. 


state_b() returns the current state (long) of randb(prob). 
randb(prob) can be re-initialized to a state returned by state_b() by calling 
initbin(seed) with the seed set to the returned state. 
SEE ALSO 
Include files: 


spd.h 
wav.h 


Signal processing library function: 


randg . 
randu 
BASIC FORMAT 


CALL brandb( prob#, number# ) 
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Where: 


prob#: 
the probability of 1, (0.0 < = prob < = 1.0) 


number#: 
- 0.0 or 1.0. 


CALL binitbin(seed&) 


Where: 


seed&: 
sets the starting state for the random number generator. 


CALL bstateb(state#) 


Where: 


state# 
the current state of brandb(prob). 
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NAME 
randg, initgaus, state g 


PURPOSE 


randg returns a pseudo-random Gaussian number of specified mean and 
standard deviation. 


initgaus initializes randg. 


state_g returns the current state of randg. 


SYNOPSIS 


#include "tekspd.h" 
double randg{mean, std} 
double mean; 

double std; 


initgaus (seed) 
long seed; 


long state_g() 


DESCRIPTION 


randg(mean,std) uses a multiplicative congruential generator to generate 12 
uniformly distributed numbers. These are linearly combined to return a 
Gaussian number of specified mean and standard deviation, std. 


randg(mean,std) is initialized to a required seed by a one-time prior call to 
initgaus (seed). In particular, the initial state of randg(mean,std) is set to the 
absolute value of seed if seed is odd, and to the absolute value of seed plus 
1, if it is even. 
If randg(mean,std) is called directly without a prior call to the initializer 
function initgaus(seed), then a starting seed of 1 is assumed. 
state_g() returns the current state (long) of randg(mean,std). 
randg(mean,std) can be re-initialized to a state returned by state_g() by call- 
ing initgaus(seed) with the seed set to the returned state. 

SEE ALSO 
Include files: — 

wav.h 


spd.h 
Signal processing library functions: 


randu 
randb 
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BASIC FORMAT 


CALL brandg(mean#, std#, number#) 


Where: 


mean#: 
the mean of the Gaussian distribution. 


std#: 
the standard deviation of the Gaussian distribution. 


number#: 
a pseudo random number from the distribution. 


CALL binitgau(seed&) 


Where: 


seed&: | 
Sets the starting state for the random number generator. 


CALL bstateg(state#) 


Where: 


state#: 
the current state of brandg(mean,std). 
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NAME 
randu, initunif, state_u 


PURPOSE oF 
randu returns a pseudo-random uniform number in [0,1]. 
initunif initializes randu. 


state_u returns the current state of randu. 


SYNOPSIS 


#include "tekspd.h" 

double randu() 

initunif(seed) 

long seed; 

long state_u() 
DESCRIPTION 


randu uses a multiplicative congruential generator to return a uniformly dis- 
tributed number in [0,1]. The period of the sequence produced on succes- 
sive calls to randu is approximately 2**29, when the initial seed is a positive 
odd number. 


randu is initialized to a required seed by a one-time prior call to in- 
itunif(seed). In particular, the initial state of randu is set to the absolute 

value of seed if seed is odd, and to the absolute value of seed plus 1, if it is 

even. 


If randu is called directly without a prior call to the initializer function in- 
itunif(seed), then a starting seed of 1 is assumed. 


state_u() returns the current state (long) of randu. 


randu can be re-initialized to a state returned by state u() by calling in- 
itunif(seed) with the seed set to the returned state. 


SEE ALSO 
Include files: 


wav.h 
spd.h 


Signal processing libarary functions: 
randg 


randb 
BASIC FORMAT ® 


Gee brandu( number# ) 


8-160 Signal Processing & Display 


Signal Processing 
randu, initunif, state_u 
Where: | 


number#: 
0.0 <= number < = 1.0. 


a CALL binitunif(seed&) 
Where: 


seed&: 
sets the starting state for the random number generator. 


CALL bstateu(state#) 


Where: 


state # 
the current state of brandu(). 
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NAME 
read num 


PURPOSE © 
Retrieves a number from a waveform. | 


SYNOPSIS 
#include "“tekspd.h" 


ERRORTYPE 
read_num(wave, tuple, index, num) 


WAVEFORM *wave; 
int tuple; 

long index[]; 
double *num 


Where: 


wave: 
pointer to the source waveform 


tuple: 
tuple to be read (numbered from zero) 


index @ 
pointer to an array of indices (coordinates) which specify the location of 
the datum to be read. (numbered from zero) | 


num: 
pointer to target variable 
DESCRIPTION 


read_num reads the number from the waveform based on the information 


in index. The value is placed into the location pointed to by num. If tuple is 
not a valid tuple number for wave, or if any of the elements of index is not a 
valid index for wave, a FATAL error will be issued. 


It is assumed that wave is a valid waveform. The number of elements in 
index must be the same as the number of dimensions in wave, otherwise 
read_num may read data from a location other than the one specified. 


SEE ALSO 
spd.h 


wav.h _ 
BASIC FORMAT 


CALL breadnum( wave%z, tuplez, index&(0), num#, statusZ ) 
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Where: 


wave %: 
integer identifying the source waveform. 


tuple To: 
tuple to be read (numbered from zero). 


index&(0): 
array of indices (coordinates) which specify the location of the datum to 
be read. (numbered from zero). 


num#: 
target variable. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
rectang 


PURPOSE _ 
Converts polar coordinates to rectangular coordinates 
SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 
rectang(mag, phase, units, delay, real, im) 


WAVEFORM *mag, “phase, *real, *im; 
UNIT units; 
double delay; 


Where: 
mag: 
pointer to the waveform containing magnitude data 


phase: 
pointer to the waveform containing phase data 


units: 
indicates whether phase is in radians, degrees, or grads rd 
delay: 
specifies a linearly varying phase adjustment 
real: 
pointer to the output waveform containing x-coordinate or real number 
data 
im: 
pointer to the output waveform containing y-coordinate or imaginary 
number data. 


DESCRIPTION 


rectang converts the data in mag and phase into real and imaginary data to 
be stored in real and im, respectively, using the formulas below: 

real_arr[i] = mag _arr[i] cos(phase_arr[i] + 2amdelay * i) 

im_arr{i] = mag _arr[i] sin(phase_arr[i] + 2mdelay * i) 
where real_arr[i], im_arr[i], mag_arr[i], and phase_arr[i] are waveform 


array values at the index 2. 

If either of the source waveforms, mag or phase, is the same as a target @ 
waveform, that source waveform is overwritten with the output data. If the 

waveform arrays are different sizes, the target waveform arrays will only be 

valid up to the length of the shortest of these arrays. If either real or im is a 

NIL pointer, the data for that waveform is simply not returned. units is 
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defined by one of three predefined keywords: RAD for radians, GRAD for 
grads, or DEGREE for degrees. 

The delay parameter causes a linearly varying phase component whose 
Slope is 2 * pi * delay to be added to the phase before polar-to-rectangular 
conversion. 

Both source waveforms and at least one target waveform must be valid. 
One target waveform pointer may be NIL. Information is taken from the 
first dimension and placed in the first dimension. The data type information 
is taken from the first tuple. 

The function returns an error code which indicates whether it was able to 
execute correctly or not. For information regarding the error code 
returned, see "spd.h". 


SEE ALSO 
Include files: 


wav.h 
spd.h 


sp.h 
Signal processing library functions: 
polar 


BASIC FORMAT 


CALL brectang(magZ, phaseZ, units2Z ,delay#, real%,im%, status2Z) 


Where: 


mag: 

integer identifying the waveform containing magnitude data. 
phase%: 

integer identifying the waveform containing phase data. 


units%: 
indicates whether phase is in radians, degrees, or grads. Use one of the 
pre-defined constants RAD%, GRAD%, or DEGREE%. 


delay#: 
specifies a linearly varying phase adjustment. 


realT%: 
integer identifying the output waveform containing x-coordinate or real 
number data. 

im%: 
integer identifying the output waveform containing y-coordinate or im- 
aginary number data. 
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status: 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 


#include "tekspd.h" 
ERRORTYPE status; 

WAVEFORM 
WAVEFORM 


status 


status 
status 


status 
status 


*mag, “phase; /* polar input */ 
*real, *imag; /* rectangular output */ 


rectang (mag, phase,DEGREE,0.0,real,imag); 


wf_dunits(dim_units(mag,0), COPY,0,real); 
wf_dunits(dim_units(mag,0), COPY,0,imag); 


wf _tunits(tup_units(mag,0), COPY,0,real); 
wf_tunits(tup_units(mag,0), COPY,0, imag); 


dim scale(real,0) = dim_scale(mag,0); 
dim _scale(imag,0) = dim_scale(mag,0); 


BASIC: 


* SINCLUDE: '\tek\spd\include\tekspd.bi’ 


magi 


= 1: phaseZz= 2 


realZ = 3: imagz = 4 


call brectang(mag%, phaseZ , DEGREEZ ,O#, realZ%,imagZz, statusZ) 


brtupunits(magZ,0,inVunitsS, inllen%,status2Z) 
bwftunits(inVunitsS,0%,real,status2Z) 
bwftunits(inVunitsS,0%,imag,statusZ) 


brdimunits(magZ,0,inHunitsS,inHlenZ,status2Z) 
bwfdunits("inHunitsS,0%,realZ,statusZ) 
bwfdunits("inHunitsS,0%,imag%, status2Z) 


brdimscale(magZ,0,hsf#,statusZ) 
bwdimscale(realZ,0,hsf#,statusZ) 
bwdimscale(imagZ,0,hsf#,statusZ) 


8-166 


Signal Processing & Display 


Signal Processing 
ft 


NAME 
rfft 


& PURPOSE 


Performs a Forward Fast Fourier Transform on real time domain data. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
rfft(time, rfreq, ifreq) 


WAVEFORM *time, *rfreq, *ifreq; 

Where: 

time: 
pointer to the waveform that contains the signal in the time domain. It 
is expected to contain only real terms. 

rfreq: 
pointer to the waveform where the real part of the frequency com- 
ponents will be stored. 

ifreq: . | 
pointer to the waveform where the imaginary part of the frequency com- 
ponents will be stored. 


DESCRIPTION 


rfft uses an FFT algorithm to compute the Discrete Fourier Transform on 
the real signal stored in time. The result is then written into the output ar- 
rays, with the real part of the transform going into sfreq and the imaginary 
part into ifreq. The data is stored in the frequency waveforms in sequential 
order with the DC term as the first element and the Nyquist term as the last. 


The length of time is required to be greater than or equal to eight. In addi- 
tion the length of zfreq and ifreq must be equal to one more than half the 
length of time. The input and output waveforms are required to be dif- 
ferent, due to the different lengths involved. Also, all three waveforms must 
be valid and none can be a NIL pointer. 


The process of computing the Discrete Fourier Transform can be thought 
of in terms of the following equation: 


© —j27nk 


N-l 
X(k] => xinle % for k= 0,1,2,..., N-l 
n=0 
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where: x[N] = Input signal 
X[k] = Complex Transform of x[n] 
N = Length of the input signal 
j = Square root of -1.0 


Real time domain signals produce frequency domain representations that 
have an even function for the real part and an odd function for the imagi- 
nary part. Therefore, only the first N/2 + 1 elements are produced in the 
Output waveform. 


This routine is designed to operate on only a single dimension and a single 
tuple of a waveform. If either an input or output waveform contains more 
than one of these, the information contained in the first will be used 
throughout the routine, and the remainder of the dimension or tuples will 
not be considered. 


The routine allocates two temporary arrays of type double and length N, 
where N is half the length of the input waveform. An error is returned if 
the required amount of memory is not available. 


This function returns an error code (as defined in the spd.h include file) in- 


dicating whether or not it was able to perform correctly. 


SEE ALSO 


Include files: 
wav.h 
spd.h 
Signal processing library functions: 
fft 
ifft 
irfft 


BASIC FORMAT 
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CALL brfft(timez, rfreqz, ifreqz, statusZ) 


Where: 


ume: 
integer identifying the waveform that contains the signal in the time 
domain. It is expected to contain only real terms. 

rfreq To: 
integer identifying the waveform where the real part of the frequency 
components will be stored. 

ifreqZe: 
integer identifying the waveform where the imaginary part of the fre- 
quency components will be stored. 
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statusTZo: 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 


is 


#include "“tekspd.h" 
ERRORTYPE status; 
WAVEFORM *time; 
WAVEFORM *rfreq, *ifreq; 
char units [80]; 


status = createl wf(dim len(time,0), tup_type(time,0), &rfreq); 
Status = createl_wf(dim len(time,0), tup_type(time,0), &ifreq); 


Status = rfft(time, rfreq, ifreq); 


strepy(units,tup_units(time,0)); /* V units from time */ 
strcat(units,” * "); 
strcat(units,dim units(time,0)); /* H units from time */ 


status = wf_tunits(units,COPY,0,rfreq); /* insert V units */ 
status = wf _tunits(units,COPY,0,ifreq); /* insert V units */ 


strepy(units,"1 / "); 

strcat(units,dim_units(time,0)); /* H units from time */ 
status = wf_dunits(units,COPY,0,rfreq); /* insert H units */ 
status = wf_dunits(units,COPY,0,ifreq); /* insert H units */ 


dim_scale(rfreq,0) = 1.0/(wave_len(time)*dim scale(time,0) ); 
dim scale(ifreq,0) = 1.0/(wave_len(time)*dim scale(time,0) ); 


status = we _mult(rfreq, dim_scale(time,0) ); 
status = wce_mult(ifreq, dim_scale(time,0) ); 


BASIC: 

" SINCLUDE: ‘'\tek\spd\include\tekspd.bi' 

timez =1 

rfreqzZ =2: ifreqZ = 3 

call brfft(magz, rfreq%, ,ifreq%, statusZ) 

' set vertical units for waveforms rfreq% and ifreqz 
brtupunits(timeZ,0,inVunitsS,inVlenZ,statusZ) 
brdimunits(timeZ,0,inHunitsS,inHlenZ, status2Z) 


bwftunits(inVunitsSt+t" * "+inHunits$,02Z,rfreq%,statusZ) 
bwftunits(inVunitsS+" * "+inHunits$,0%,ifreq%,status2Z) 


bwfdunits("1 / "tinHunitsS,0%,rfreqZ,statusZ) 
bwfdunits("1 / “+tinHunitsS,0%,ifreq%,statusZ) 


" scale the output waveforms 
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bwavelen(timeZ, length&, status7Z) 
brdimscale(timez, 0, hsf#, statusZ) 


bwdimscale(rfreqz, 0, 1 / (length& * hsf#), status7Z) 
bwdimscale(ifreqz, 0, 1 / (length& * hsf#), status2) 


bwemult(rfreqZ, hsf#, status2) 
bwemult(ifreq%, hsf#, status2) 
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NAME 
rpt_count 


PURPOSE | 
Reports the occurrence of an error to the error output device. 


SYNOPSIS 


#include "tekspd.h" 
rpt_count(errtype, errcount, errmsg) 


ERRORTYPE errtype; 
long errcount; 
char *errmsg; 


Where: 


errtype: 
type of error. It should be one of NOERROR, WARN, FATAL or 
CRASH. 


errcount: 

the number of times the error has been detected. 
errmsg: 

error message string describing the nature of the error. 


DESCRIPTION 


rpt_count sends a multi-line message to the error device as set up by err _file. 
The first line is blank followed by the number of errors detected (errcount), 
type of error (errtype) and list of called functions that led to this error on 
the second line. The third and following lines contain the text of the errmsg 
string. 

rpt_count is useful for accumulating certain types of errors that may be 
produced in large numbers (i.e., floating point exceptions) and issuing them 
at one time. 


The following is an example output of a WARNing error that was detected 
five times from a routine (func_2) which has been called from another 
routine (func_1): 


5 of the following WARNING ERRORS in func_1: func_2: 
Warning error message string. 


If errtype is CRASH, a user written routine shut_down is called to perform 
any needed cleanup operations before the program is aborted. 


SEE ALSO 
Include files: 


spd.h 


Signal Processing & Display 8-17] 


Signal Processing 


rpt_count 


Signal processing library functions: 


clr_err 
err file 


rpt_err 
set_err 
shut_down 


BASIC FORMAT 


CALL brptcount( errtypeZ%, errcount&, errmsgS ) 


Where: 


errtype Zo 
type of error, it should be one of NOERROR%, WARN%, FATAL%, 


or CRASH%. 


errcountd&: 
the number of times the error was detected. 


errmsg: 
error message string describing the nature of the error. 
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NAME 
rpt_err 
PURPOSE 


Reports the occurrence of an error to the error output device. 
SYNOPSIS 


#include "tekspd.h" 
rpt_err (errtype, errmsg) 


ERRORTYPE errtype; 
char *errmsg; 


Where: 
errtype: 
type of error (NOERROR, WARN, FATAL, or CRASH). 
errmsg: 
error message string describing the nature of the error. 
DESCRIPTION 


rpt_err sends a multi-line message to the error device as set up by err_file. 
The first line is blank followed by the type of error (errtype) and list of 
called functions that led to this error on the second line. The third and fol- 
lowing lines contain the text of the errmsg string. 


The following is an example output of a FATAL error message from a 
routine (func_2) which has been called from another routine (func_1): 


FATAL ERROR in func_1: func_2: 
Fatal error message string. 


If errtype is CRASH, a user written routine shut_down is called to perform 
any needed cleanup operations before the program is aborted. 
SEE ALSO 
Include files: 
spd.h 
Signal processing library functions: 


clr_err 

err file 
rpt_count 
set_err 
shut_down 
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BASIC FORMAT 
CALL brpterr(errtypeZ, errmsgS) 
Where: 
errtype To: 


type of error; it should be one of NOERROR%, WARN%, FATAL%, 


or CRASH%. 


errmsg$: 


error message string describing the nature of the error. 
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NAME 
Sset_ err 


© PURPOSE 
Saves the name of the executing function for use by the error handler. 
SYNOPSIS 


#include "tekspd.h”" 
set_err (funcname) 


char *funcname; 


Where: 


funcname: 
name of the function currently executing. 


DESCRIPTION 


set_err saves the name of the currently executing function for use by the 
error handling functions rpt_err and rpt_count. 


set_err operates by pushing the function name on a stack. Nested function 
calls to five levels deep are saved in this manner. If more than five levels 

& are called, a counter maintains the nesting level. When rpt_err or rpt_count 
is called, the stack and function level information is used to output the list 
of called functions that produced the error. c/r_err is used to pop the func- 
tion name off the stack. 


Typically, set_err is one of the first executable statements in a function call. 
Any errors are then reported through calls to rpt_err or rpt_count. The last 
statement before a return is a call to c/r_err to pop the function name from 
the stack. 


SEE ALSO 
Include files: 
spd.h 
Signal processing library functions: 


clr_err 
rpt_count 
rpt_err 


6 BASIC FORMAT 


CALL bseterr(funcname$S) 
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set_err 
Where: 
funcname$: 


name of the function currently executing. 
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NAME 
shut_down 


o PURPOSE 
User written function to handle any shutdown processing in the event a 
CRASH error occurs. 


SYNOPSIS 
shut_down() 


DESCRIPTION 


shut_down is a function used to reset the operating environment to a 
default state before exiting a program when a CRASH error occurs. This 
function should be tailored to the specific clean up needs of a running ap- 
plication program. 


This function, as supplied, simply returns without doing anything. 


SEE ALSO 
Signal processing library functions: 
rpt_err 


@ rpt_count 
BASIC FORMAT 


CALL bshutdown 
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NAME 
sin2 


PURPOSE 
Calculates points for a single pulse of the function sin?(x) and stores them 
in a waveform array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTY PE 
sin2(ampl,width, pkpoint, baseline, wave) 
double ampl,width, pkpoint, baseline; 


WAVEFORM *wave; 


Where: 
ampl: 

pulse amplitude: the difference between DC offset and peak amplitude. 
width: 

width of pulse at half its amplitude. 


pkpont: 
offset of pulse from the center of the waveform. 


baseline: 
baseline (reference) amplitude. 


wave: 

pointer to the target waveform. 

DESCRIPTION 

sin2 generates successive points of a pulse of the sin?(x) function via the fol- 
lowing equation: 

first, for n = 0 to (start - 1) 

x[n] = baseline 
then, for n = start to end 


x(n] = 2mpl [eos am - phase 


and finally, forn = end + ltoN-1 


+ 1 + baseline 


x(n] = baseline 
where: 
Nn = array index 
N = number of points in waveform array 
Start = first point of pulse: smallest integer 
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> = + pkpoint - width 
end = last point of pulse: largest integer 
< = + pkpoint + width 
t = period of raised cosine wave: 2:width 
phase = delay from beginning of waveform to center of pulse: 


a = + pkpoia| 


The waveform must be valid. width cannot be zero or negative. If it is, sin2 
returns a FATAL error. The function stores data in the first tuple of the 
first dimension of the output waveform array. 


This function returns an error code (as defined in tahe spd.h include file) in- 
dicating whether or not is executed correctly. 


SEE ALSO 
Include file: 
wav.h 
spd.h 
BASIC FORMAT 


CALL bsin2(ampl#, width#, pkpoint#, dc#, waveZ, status2Z) 


Where: 
ampl#: 

pulse amplitude: the difference between DC offset and peak amplitude. 
width #: 

width of pulse at half its amplitude. 


pkpoint#: 
offset of pulse from the center of the waveform. 


dc#: 


baseline (reference) amplitude. 


wave J: 
integer identifying the target waveform. 


_ status%: 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
sinc 


PURPOSE ©} 
Calculates points for the sinc and stores them in a waveform array. 
SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 
sinc(smpl, freq, pkpoint, baseline, wave) 
double ampl, freq, pkpoint, baseline; 


WAVEFORM *wave; 


Where: 
ampl: 
signal amplitude at the center of the pulse. 


freq: 
sinc frequency. 


pkpoint: 
delay of the center of the pulse from the center of the waveform. © 


baseline: 
baseline reference amplitude. 


wave: 
pointer to the target waveform. 


DESCRIPTION 
sinc generates successive points of sinc function via the following equation: 
forn = OtoN-1 


x(n) =27p! + sia(nw + freq -phase) Raceline 


nt ° /reg - phase 


where: 


n = number of points in waveform array 
n = array idex: 0,1,..., n-1 
phase = delay from beginning of waveform to peak of sinc function: 


w freq = ra pkpoint @ 


The waveform must be valid. Data is written into the first tuple of the first 
dimension of the output waveform array. 
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This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 


SEE ALSO 


Include files: 


wav.h 
spd.h 


BASIC FORMAT 


CALL bsinc(ampl#, freq#, pkpoint#, dc#, wave%, statusZ) 


Where: 
ampl#: 

signal amplitude at the center of the pulse. 
freq#: 


sinc frequency. 


pkpoint#: 
delay of the center of the pulse from the center of the waveform. 


dc#: 
baseline reference amplitude. 
wave %: 
integer identifying the target waveform. 


status Zo: 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 


sinemeas 


PURPOSE 
Computes the amplitude, frequency and phase of up to ten additive sine 
wave components of the input waveform. 


SYNOPSIS 
#include "tekspd.h”" 


ERRORTYPE 
sinemeas (wave, window, threshold, phunits, ampl, freq, phase) 


WAVEFORM *wave; 

int window; 

UNIT phunits; 

double threshold, ampl[{], freq[{], phase[]; 


Where: 


wave: 
pointer to the input waveform. 


window: 
predefined constant specifying the window to apply to wave. The 
keywords are: RECTANGULAR, TRIANGULAR, HANNING, HAM- 
MING, BLACKMAN, or FLATTOP. 

threshold: 


desired amplitude detection range from the maximum sine wave com- 
ponent. 


phunits: 
the units that phase is to be stored in. It must be either RAD, DE- 
GREE or GRAD. 

ampl[]: ' 
array to contain the amplitudes sorted in decreasing order. Its length 
must be at least equal to 10. If it is NIL, then no output is generated 
for this parameter. 

freq{]: 
array to contain the frequencies. freq/k] corresponds to ampl/[k]. The 
length of the array must be at least equal to 10. If it is NIL, then no out- 
put is generated for this parameter. 


phase[]: 
array to contain the phases. phase/k] corresponds to ampl/[k]. The a 


length of the array must be at least equal to 10. If it is NIL, then no out- 
put is generated for this parameter. 
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DESCRIPTION 
sinemeas determines the dominant sine wave parameters in wave such that: 


waveln] = > amp! [i] - sin(2w - fregli] - n + phase [i)) 


The parameters of the most dominant of these sine waves (one with the 
largest amplitude) is stored in ampl/0], freq[0] and phase/[0]. Lesser 
dominant sine waves are stored in decreasing amplitude order in successive 
elements of the output arrays. The parameters of a sine wave will be output 
if its amplitude is one of the ten greatest values and meets the criteria: 

If less than 10 sine waves meet this criteria, the unused output array loca- 
tions are filled with 0.0. 


sinemeas uses an approximate maximum likelihood algorithm to compute 
the sine wave parameters. The measurement procedure is as follows: 


The mean is computed and subtracted from the input signal. 
The input signal is windowed by window. 


The discrete fourier transform is taken (7fft) and the output converted 
to polar form (polar). 


A coarse search is performed on the magnitude array to locate the 
dominant signal peaks. 


Finally, interpolation is carried out at each dominant peak location to 
determine the precise frequency, amplitude and phase values. 


For the most accurate performance, the dominant sine wave components of 
wave must be spaced so that the main lobes of the windowing function do 
not overlap. An indicator of this required distance is the 6 dB bandwidth of 
the window. The table below lists these bandwidths for the available win- 
dows. 


threshold may vary from 1.0 (which only allows selection of the dominant 
sine wave component) down to the value of the highest side lobe for the 
selected window. The table below lists the lower limits of the threshold 
values for each window. Setting threshold to 0.0 causes sinemeas to set the 
threshold to the value in the table for the selected window. If threshold is 
out of range, sinemeas issues a warning error and sets the threshold to the 
value in the table for the selected window. 
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____________________ Window Spectral Characteristics 
Window Threshold 6 dB Bandwidth 
(frequency bins) 

RECTANGULAR 0.22 1.21 | 
TRIANGULAR 0.048 Ld? © 
HANNING 0.027 2.00 
HAMMING 0.0077 1.82 
BLACKMAN 0.0013 2.30 
FLATTOP 0.000025 2.67 


sinemeas operates only on the first dimension and first tuple of the input 
waveform wave. 


sinemeas returns a FATAL error and does not compute any parameters if 
any of the following conditions occur: 

There is not enough memory available for temporary work area. 

The input waveform is not valid. 

The windowing function is not one of the predefined types. 

The phase unit is not RAD, GRAD, or DEGREE. 


This function returns an error code (as defined in the spd.h include file) in- & 
dicating whether or not it executed correctly. 
SEE ALSO 
Include files: 
sp.h 
spd.h 
wav.h 
Signal processing functions: 


polar 
rfft 
taper 


BASIC FORMAT 


CALL bsinemeas( waveZ, windowZ, thresh#, phunitsZ, ampl#(0), 
freq#(0), phase#(0), statusZ ) 


Where: e 
wave Jo: 
integer identifying the waveform to be measured 


window%: 
integer identifying the window function to apply: 
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Predefined constant specifying the window to apply to wave%. The 
keywords are: RECTANGULAR%, TRIANGULAR%, HAN- 
NING%, HAMMING%, BLACKMAN%, or FLATTOP%. 


thresh#: 
desired amplitude detection range from the maximum sine wave com- 
ponent 


phunits%: 
integer indicating the units that phase is to be stored in. Predefined 
constants include: 


RAD% for radians, 
GRAD for grads, 
DEGREE% for degrees. 
ampl# (0): 
a double precision floating point array that will contain the amplitudes 


sorted in decreasing order. The array length must be at least equal to 
10. 


freq# (0): 
a double precision floating point array that will contain the frequencies. 
freq(k) corresponds to ampl(k). The array length must be at least equal 
to 10. 

phase# (0): 
a double precision floating point array that will contain the phases. 


phase(k) corresponds to ampl(k). The array length must be at least 
equal to 10. 


status%: 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
C: 


#include "tekspd.h" 
ERRORTYPE status; 


short is 

WAVEFORM *wave; 

double amplitude[(10], frequency[10], phase[10]; 
double scale; 


status = sinemeas(wave, HANNING, 0.0, DEGREE, 
amplitude, frequency, phase); 


scale = wave_len(wave)*dim scale(wave,0); 
for (i=0; i; i++) /** scale freq to phase units **/ 
frequency /= scale; 
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BASIC: 


‘ SINCLUDE: '\tek\spd\include\tekspd.bi’ 
wavez = 1 


DIM ampl#(10) 
DIM freq#(10) © 
DIM phase#(10) 
call bsinemeas(wave%, FLATTOPZ, 0.0, DEGREEZ, freq#(0), 
ampl#(0), phase#(0), statusZ) 


call bwavelen(waveZ, length&, status2Z) 
call brdimscale(waveZ, 0%, hsf#, status2Z) 
scale# = lengthé& * hsf# 
FOR iZ = 0 to 9 

freq(iz) = freq(iz) / scale# 
NEXT i2 
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NAME 


sinewave 


PURPOSE 
Generates successive points of a sine wave and stores them in a waveform 
array. 


SYNOPSIS 


#include "tekspd.h" 
ERRORTYPE 
Sinewave (ampl, freq, phase, base, wave) 


double ampl, freq, phase, base; 
WAVEFORM *wave; — 


Where: 
ampl: 

signal amplitude. 
freq: 
signal frequency (fraction of cycle per sampling interval). 


phase: 
initial phase (in radians). 


base: 
baseline offset or reference level of the sine wave (value at sin(0)). 


wave: 
pointer to the target waveform. 


DESCRIPTION 


sinewave generates successive points of a sine wave array according to the 
following equation: 


forn = Oto size-1 


x[n] = ampl * sin(27 * freq * n + phase) + base 


where: 
amp! = amplitude of the sine wave 
phase = initial phase of the sine wave 
base = baseline amplitude of the sine wave (value at sin(0)). 
size = number of points in waveform array 
n= array index 


The waveform must be valid. Data is written into the first tuple of each ele- 
ment of the first dimension of the waveform. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 
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SEE ALSO 
Include files: 


spd.h 
wav.h | © 
BASIC FORMAT 


CALL bsinewave( ampl#, freq#, phase#, dc#, wavez, status2Z ) 


Where: 


ampl#: 
signal amplitude. 
freq#: 
signal frequency (fraction of cycle per sampling interval). 
phase#: 
initial phase (in radians). 
dc#: 
baseline offset or reference level of the sine wave (value at sin(0)). 


wave%: 
integer identifying the target waveform. 


statusTo 
integer indicating the execution status of the function. Result will be ©@ 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 


Square _wave 


PURPOSE 


Creates a square wave with either ramped or sine-squared edges, given the 
various components of the waveform. 


SYNOPSIS | 
#include "tekspd.h" 


ERRORTYPE 
Square wave(amp, period, offset, delay, duty, risetype, risetime, 
falltype, falltime, wave) 


double amp, period, offset, delay, duty, risetime, falltime; 
TRANSTYPE risetype, falltype; 
WAVEFORM *wave; 


Where: 
amp: 

amplitude is the difference between the highest and lowest amplitudes. 
penod: 

length of one waveform cycle. 


offset: 


value of the initial amplitude. 


delay: 
offset from the beginning of the array to amp/2 point on first transition. 
duty: 
ratio of pulse duration to the period length, where the pulse duration is 
the amount of time at amplitude > amp/2. 
nsetype: 
type of transition for rising-edge (RAMP or SIN2). 


nsetime: 
time spent between 10% and 90% of amp in rising-edge transition. 


falltype 
type of transition for falling-edge (RAMP or SIN2). 


falltime: 
time spent between 90% and 10% of amp in falling-edge transition. 


wave: 
pointer to waveform in which to store generated data. 
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DESCRIPTION 


square_wave generates a waveform that is stored in the first dimension and 
the first tuple of wave. By specifying the various components of a 
waveform passed in through the parameters, a waveform can be defined. _ 


nisetype and falltype can be specified by the flagwords: 


RAMP: 
The rising edge transition is linear with the amplitude computed as: 


y(t) = amp— + offset 


and the falling edge transition is linear with the amplitude computed as: 


y(t)= amp [!- a + offset 


where 

y = amplitude at time ¢. 

t = instance in time where 0<t <T. 

T = total transition time = 1.25 * nsetime or 1.25 * falltime. 

amp = transition amplitude. 

offset = baseline offset. 

t=0 is the starting time of the transistion. 
SIN2: © 
The shape of a sin? transition is computed as the integral of a sin? pulse. 


For the rising edge this translates into the equation: 


y(t)= amp + - — S10 [AF] + offset 
Similarly the falling edge translates into the equation: 
y(t)= amp [!- T| * Se sin [4a + offset 


y = amplitude at time ¢. 

t = instance in time where 0<t <T. 

pf = total transition time = 2.073878 * risetime or 
2.073878 * falltime. 

amp = transition amplitude. 

offset = baseline offset. 

t=0 is the starting time of the transition. 


With both types, the rise time is from 10% to 90% of amplitude, the fall 
time is from 90% to 10% of amplitude, and the duty cycle is the ratio of the 
time above 50% amplitude to the period. 3 


A FATAL error is returned and a square wave is not generated if: 
The waveform is not valid. 
The period is less than or equal to zero. 
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The duty factor is not between zero and one. 
The nisetype and falltype are not RAMP or SIN2. 
The risetime and falltime is less than or equal to zero. 


The nsetime and falltime are longer than can be achieved with the given 
duty cycle and period. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 


SEE ALSO 
Include files: 
sp.h 
spd.h 
wav.h 


BASIC FORMAT 


CALL bsquarewave( amp#, period#, offset#, delay#, duty#, ris- 
typez, risetime#, falltypeZ, falltime#, waveZ, statusZ ) 


Where: 
amp# 
amplitude -- the difference between the highest and lowest amplitudes. — 
penod# 
length of one waveform cycle. 
offset# 
value of the initial amplitude. 
delay# 
offset from the beginning of the array to amp/2 point on first transition. 
duty# 
ratio of pulse duration to the period length, where the pulse duration is 
the amount of time at amplitude > amp/2. 
nsetypeYo 
type of transition for rising edge: use the predefined constant 


RASMP% or SIN2%. 


nsetine# 
time spent between 10% and 90% of amp in rising-edge transition. 


falltype% 
type of transition for falling-edge: use the predefined constant 


RASMP% or SIN2%. 


falltime# 
time spent between 90% and 10% of amp in falling-edge transition. 


wave % 
integer identifying the waveform in which to store generated data. 
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status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 


sumave 


PURPOSE 


Sums or averages the elements of an n-dimensional waveform, along one 
dimension to produce an n-1 dimensional waveform. 


SYNOP[SIS 


#include "“tekspd.h" 


ERRORTY PE 
sumave(in, flagword, sumdim, out) 


WAVEFORM *in; 
int flagword, sumdim; 
WAVEFORM *out; 


Where: 
in: 
pointer to the waveform containing data to be summed or averaged. 
flagword: 
flag word, AVE or SUM, indicating whether elements should be 
averaged or just summed. 


sumdim: 
dimension along which all the other dimensions will be summed or 
averaged; for example, zero denotes the first dimension, one denotes 
the second, and so forth. 


out: 
pointer to the waveform in which to place generated data. 


DESCRIPTION 


sumave adds up all the other dimensions along the dimension sumdim. If 
flagword is AVE, the average is then found. The output is put into the first 
n-1 dimensions of the output waveform, where 7 is the number of dimen- 
sions of the input waveform. More concretely, if a two-dimensional 
waveform is passed through surmave, either the rows or the columns will be 
added, depending upon which dimension is given as sumdim. If there are 
three rows and the row dimension was passed in as sumdim, the waveform, 
out, will contain three elements; the first corresponds to the sum or average 
of the first row and so on. If a three-dimensional waveform is given, the 
waveform will be summed or averaged along the sumdim dimension and 
- the results will be placed in a two-dimensional area. In the three-dimen- 
sional case where surndim is one: 


view! 
outearrixlz] = >> in_arrixJylz] 
y=0 
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for0 < x < xlenand0O < z < zlen 
where: 


y was chosen as the dimension along which to operate. 
out_arr and in_arr are the waveform arrays. 
xlen, ylen, and zlen are the dimension lengths. 


In the general case: 
aleni-i 
out—arr(x,] (xo)...[x)-.] [xia]...024] = > in_acrlxs){xg)...fx 5s] % Oxi)... [22] 
I,-6 
for 
0 < x; < xlen,0 < x2 < xlem,..., 
0 < xj-1 < xlenj-1,0 < xj41 < xlenj41,..., 
0 < Xp < xleny 
where: 


x1 was chosen as the dimension along which to operate. 
out_arr and in_arr are the waveform arrays. 
xlen 1, xlen2, ..., xlenn are the dimension lengths. 


This routine is designed to operate on multi-dimensional waveforms that 

contain only a single tuple. If the input waveform contains more than a 

single tuple, all information will be taken from the first and the remainder 6 
will not be considered. 


The waveforms must be valid, and the dimension size must be at least two 
for the input waveform. in and out cannot be the same waveforms. If the 
two waveform arrays are not the same length for a given dimension, that 
dimension of the target waveform array will only be valid to the length of 
the shorter waveform array. If the source waveform is of dimension 7, the 
target waveform must be at least of dimension n-1 and susmdim must be a 
dimension that exists in the source waveform (e.g., 0 < = sumdim <n). If 
the target waveform has more dimensions, only the first n-1 dimensions will 
be written into. 


The function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 


SEE ALSO 
Include files: 


wav.h 


spd.h 
sp.h 


8-194 Signal Processing & Display 


sSumave 


Signal Processing 


BASIC FORMAT 


CALL bsumave(in%, flagword%, sumdim%, outZ, status2Z) 


Where: 


ino: 
integer identifying the waveform containing data to be summed or 
averaged. 

flagword[% 
integer indicating whether elements should be averaged or just 
summed. Use the predefined constants SUM% or AVE%. 


sumdim Yo 
dimension along which all the other dimensions will be summed or 
averaged; for example, zero denotes the first dimension, one denotes 
the second, and so forth. 


out% 
integer identifying the waveform in which to place generated data. 


status To 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
taper 


PURPOSE 
Windows a waveform with a selected windowing function. 


SYNOPSIS 
#include "tekspd.h" 
ERRORTYPE taper(inwav, wd, per, outwav) 


WAVEFORM *inwav, *outwav; 
int wd; 
double per; 


Where: 


inwav: 

pointer to the input waveform whose values are to be windowed. 
wd: 

predefined keyword specifying the window function to apply. 
per: 


percentage of the input waveform over which the window is to be ap- 
plied. 


outwav: 
pointer to the output waveform that is to hold the windowed result. 


DESCRIPTION 


taper multiplies the input waveform, inwav, by the windowing function 
specified by wd and per, and then overwrites outwav with the result. 


The tapering percentage, per, must be a double precision number between 
0.0 and 1.0, inclusive. It corresponds to the percentage of the smaller of the 
two arrays over which the window will be applied. The percentage is 
measured equally from the two ends of the array. Thus, if per is specified as 
0.8, the center 20% of the array will be not windowed. The actual number 
of points that will be windowed corresponds to the product of the percent- 
age and the number of points in the smaller of the two specified arrays. If 
the output waveform is smaller than the input waveform, the function will 
treat the input waveform as if it were truncated to the same size as the out- 
put. It will then symmetrically window each end of the new input waveform 
and place it in the output. However, if the output waveform is larger than 
the input waveform, the routine will treat the output waveform as if it were 
equal in size to the input waveform. It will then symmetrically window the 
waveform and fill any extra elements with zeros. 
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The selected windowing function, wd, must be one of six predefined 
keywords. Each is listed below along with its corresponding algorithm. 


RECTANGULAR 
_ 0.0 
a(n} =; 1.0 
0.0 
TRIAN 


n 
a(n] = 1.0 
r/N 


HANNING 
| 0.5(1—cos(2xn/N)) 
a(n] = 1.0 
0.5(1—cos(2ar/N)) 
| 0.54—-0.46-cos(22n/N) 
a(n] = 1.0 
0.54—0.46-cos(2xr/N) 
_BLACKMAN 


I 0.42—0.50-cos(29n/N)+0.08-cos(4en/N) 
a(n] = 1.0 
0.42—0.50-cos(2ar /N)+0.08-cos(4xr /N) 


FLATTOP 
0.35875—0.48829-cos(2xn/N)+0.14128-cos(4en/N) 
—0.01 168-cos(6#n/N) 
a(n] = { 1.0 
0.35875—0.48829-cos(29r/N)+0.14128-cos(4zr/N) 
~0.01 168-cos(6rr/N) 
where: 


L = number of elements in array 

per = fractional amount of array to window [0,1] 
n = index of array element 

r=L-n 

N = L* per 

M=N/2 


Oogn<M 


M€en<L=-M 
L=-Men<L 


Some of the characteristics of each window are listed in the table below. 
The characteristics are defined for windows of length, L (where L is defined 
in the equations above) and 100% tapering (per = 1.0). The RECTAN- 
GULAR window is defined over a length, N, where N is defined above. 
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Window Spectral Characteristics 


Window Major Lobe Highest Side Bandwidth Theoretical 
Height Lobe (dB) (-3 dB) Roll-off 
(dB/Octave) 
RECTANGULAR 100*N -13.2 0.89/N 6 
TRIANGULAR 0.50 * L -26.4 1.28/L iZ 
HANNING 0.50 * L -31.4 1.44/L 18 
HAMMING 0.54 *L 42.3 1.30/L 6 
BLACKMAN 0.42 *L -58.1 1.64/L 18 


FLATTOP 0.36 *L -92.1 1.90/L 6 


A graph of each window function and its corresponding frequency domain 
plot is shown below. The frequency plots have been normalized for a zero 
dB main lobe amplitude and span a frequency range of zero to one half the 
sampling frequency (fs). 

Taper is designed to operate on only a single dimension and a single tuple 
of a waveform. If either the input or output waveform has more than one of 
these, the information contained in the first will be used throughout the 
routine, and the remainder of the dimension or tuples will not be con- 
sidered. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 

SEE ALSO 
Include files: 


spd.h 
wav.h 
sp-h 


BASIC FORMAT 


CALL btaper(inwavZ, wdZ, per#, outwav%, statusZ) 


Where: 


inwavZo 
integer identifying the input waveform whose values are to be win- 
dowed. 

wd% 
integer indicating the window function to apply. 


Predefined constant specifying the window to apply to wave%. The 
keywords are: RECTANGULAR%, TRIANGULAR%, HAN- 
NING%, HAMMING%, BLACKMAN%, or FLATTOP%. 
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per# 
percentage of the input waveform over which the window is to be ap- 
plied. 
outwav% 
integer identifying the output waveform that is to hold the windowed 
result. 


status % 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


: RECTANGULAR Window of requency Transform 
1 


Frequency (fs) . 


io LRIANGULAR Window of requency Transform 


O.2 a3 Ove oo 
Frequency (fs) 


- HANNING Window 


Frequency Tronsform 


Log Mog. (4B) 


Frequency (fs) 
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( AMMING Window of requency Transform - @ 


Frequency (fs) 


. Frequency Transform 


Frequency (fs) 


7 Frequency Transform 


Frequency (fs) 
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NAME 
tup_reorder 


PURPOSE 


Changes the order and number of tuples in a waveform data element. 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
tup_reorder (wave, ntups, order, del_keep, subwave) 


WAVEFORM *wave; 
int ntups, order[], del _ keep; 
WAVEFORM **subwave; 


Where: 


wave: 

pointer to the source waveform. 
— ntups: 

new number of tuples in the waveform data element. 

order: 
address of an array containing the new order of the tuples in terms of 
the current tuple numbers. (Tuples are numbered from zero.)  ‘ 

del keep: 
flagword used to indicate whether the source waveform should be 
deleted if possible; defined values are DELETE or KEEP. 


subwave: 
address of the pointer to the subordinate waveform to be created. 


DESCRIPTION 


tup_reorder allocates memory space for a subordinate waveform structure 
and its associated substructures. It returns the address of the new subor- 
dinated waveform in subwave. 


The new waveform is similar to the source except that the number of tuples 
may be fewer and the order of the tuples may be different. When forming 
the new waveform, this function copies the information about the specified 
tuples of the source waveform in the specified order, and calculates the new 

data element size. It does not change the order or number of the dimen- 
sions. 


tup_reorder does not delete or rearrange any array data, but the unused 
tuples are not accessible from the new subordinate waveform. However, by 
using copy _wf() on the resultant waveform, a new waveform with com- 
pacted and rearranged array data can be created. 
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tup_reorder may also attempt to delete the source waveform, wave, depend- 
ing on the value of del_keep and whether wave is an original waveform or 
not. If del_keep is DELETE and wave is not an original waveform, subwave 
is made subordinate to the previous waveform of wave, the subordinate 
counter of the previous waveform of wave is incremented, and an attempt is 
made to delete wave. If not, subwave is made a subordinate of wave and the 
subordinate counter of wave is incremented. 


String fields (titles, notes, dimension labels, dimension units, tuple labels 
and tuple units) for subwave are LINKed to the string information in wave. 
That is, the pointer to the string in wave is copied to subwave, but the cor- 
responding bit in the bit flags field is reset indicating that no memory was 
allocated for subwave to contain the string. When space has been allocated 
for a string in wave and wave is to be DELETEd, the appropriate bit flag is 
set in subwave so that the strings will be properly maintained. 


The information in the new WAVEFORM structure is copied from the 
source except: 


The pointer to the previous waveform is set to either wave or the pre- 
vious waveform of wave as explained above. 


The number of subordinate waveforms is set to zero. 


The bit flags are set to show that the structure space was allocated by 
one of the waveform utilities and can, therefore, be released by them. 


The setting of the bit flags for string fields (title and notes) are 
described above. 


The new data element size is calculated as the sum of the byte lengths 
of the data types for the new number of tuples. 


The array pointer is adjusted to point to the new first tuple of the first 
element of the waveform array. 


The pointer to the substructures containing dimension information 
points to the W_DIM structure for the first dimension of the new 
waveform. 

The number of tuples is set to ntups. 


The pointer to the substructures containing the tuple information 
points to the W_TUPLE structure for the first tuple of the new 
waveform. 


The information in the W_DIM structures of the new waveform is copied 
from the source without changing the order or number of the W_DIMs ex- 
cept the string field bit flags for dimension labels and units as described 
above. 


The information in the mtups W_TUPLE structures of the source is copied 
to the new waveform in the order specified by order[] except: 


The string field bit flags for tuple labels and units are set as described 
above. 
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The byte offset from the first tuple is adjusted. 
tup_reorder issues a FATAL error if: 

wave is not a valid waveform. 

ntups < 1 or ntups > the number of tuples in wave. 


Any of the tuple numbers in order[{] are < 0 or > = the number of 
tuples in wave. 


Any tuple number appears more than once in order{]. 

There is not enough free memory available for the new structures. 
tup_reorder issues a WARNing error if: 

del_keep is not KEEP or DELETE; KEEP is assumed. 


wave is a subordinate waveform and del_keep is DELETE, but wave 
cannot be deleted (i.e., the bit flags do not indicate that the structure 
space was allocated by one of the waveform utilities or the subordinate 
waveform counter is not zero). 


If a FATAL error occurs, *subwave is set to NIL. 


SEE ALSO 
Include files: 
spd.h 
wav.h 
Signal processing files: 
dim_reorder 
make_subwf 
zone_dim 
NOTES 


If subwave points to the address of wave upon function entry, it is then the 
user’s responsibility to note the waveform structure previously associated 
with wave. 


BASIC FORMAT 
CALL btupreorder( wave%Z, ntupsZ, orderz(0), delkeep%, subwaveZ, 
statusZ ) 
Where: 


wave Yo 
integer identifying the source waveform. 


ntupsZo 
new number of tuples in the waveform data element. 


order%(0) 
array containing the new order of the tuples in terms of the current 


tuple numbers. (Tuples are numbered from zero.) 
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delkeep% 
flagword used to indicate whether the source waveform should be 
deleted if possible. Result will be one of NOERROR%, WARN%, 
FATAL% 


subwave ZY 
integer identifying the subordinate waveform to be created. 


status 7% 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
validcheck 


PURPOSE 


Tests a waveform data structure for validity. 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
validcheck (wave) 


WAVEFORM *wave; 


DESCRIPTION 


validcheck tests for the validity and consistency of the waveform structure 
pointed to by wave according to the following definition of a valid 
waveform: 


The pointer to the waveform is not NIL. 

The pointer to the array data is not NIL. 

The pointer to the dimension data is not NIL. 

The pointer to the tuple data is not NIL. 

The pointer to the waveform’s previous waveform is not itself. 
The size of the waveform array is > = 1. 

The number of dimensions is > = 1 and < = MAXDIMS. 
The number of tuples is > = 1 and < = MAXTUPS. 


The number of subsequent waveforms which point to this waveform as 
their previous waveform is > = 0. 


For each tuple, the data type is valid (e.g., W SHORT, W_LONG, 
W_FLOAT, or W_DOUBLE). 


The size (in bytes) of the data element must < = the sum of the sizes of 
the tuples. 


The offset (in bytes) from the first tuple for the first tuple must be zero. 
For each dimension, the length is > = 1. 


For each dimension, the increment (in bytes) to the next element is an 
even number > = 0. (An increment of 0 allows a waveform to be — 
"filled" with the same constant data element without taking up memory.) 


The size of the waveform equals the product of the lengths of the 
dimensions. 


If the waveform is an original waveform (i.e., its waveform block does 
not point to a previous waveform block), its array data is contiguous. 
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This means that the size of the data element * the number of elements 
in the array equals the size of the data element + the summation, as i = 
0, 1, 2, ... N-1, of the increment to the next element * (the length - 1) for 
each dimension, i, where N is the number of dimensions. 

If the waveform block points to a previous waveform block, its array 
data is entirely within the bounds of the array data of the original 
waveform (i.e., the address of the first byte of original waveform’s array 
is < = the address of the first byte of the current waveform’s array, 
which is < the address of the last byte of the current waveform’s array, 
which is < = to the address of the last byte of the original waveform’s 
array). 


NOTE 
Since the size of the data element must be even and at least two, the ad- 
dress of the last byte must be > the address of the array data. 


If the wave is valid then validcheck returns NOERROR. If anything is 
found wrong in the data structure an error message is issued describing the 
problem and FATAL is returned. 
SEE ALSO 
Include files: 
spd.h 
wav.h 


BASIC FORMAT 


CALL bvalidcheck(wave%, statusZ ) 


Where: 
wave%: 
integer identifying the waveform to be checked. 


status%o: 
integer indicating the execution status of the function. Result will be 


one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
w_add 


PURPOSE 
Adds corresponding elements of two n-dimensional input waveform arrays 
and places the sums in an n-dimensional output waveform array. 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
w_add(inl, in2, out) 


WAVEFORM *inl, *in2, *out; 


Where: 
ind: 
pointer to one input waveform. 
in2: 
pointer to the other input waveform. 


out: 


pointer to the output waveform that will hold the sums of elements of 
inl and in2. 


DESCRIPTION 


The least number of dimensions and the least number of elements in any 
given dimension of in1 or in2 or out are used as the basis for determining 
the extent to which out is "filled" with sums. For example, if inJ has 4 ele- 
ments along its first dimension, in2 has 2 elements along its first dimension 
and out has 3 elements along its first dimension, the first 2 elements along 
the first dimension of out will be "filled" with sums. 


The following examples should make this clear: 


inl in2 out Portion of out holding sums 
4x4x3 3x4x4 2x2 2x2 

1x4x1 4x1x1 1x1x4 1x1x1 (or 1 element) 

2x2x2 2x2x2 4x4 2x2 

4x4x4 4x4x4 4x4x4 4x4x4 


where 4x4x3 means "4 elements alont the first dimension, 4 elements along 
the second dimension, and 3 elements along the third dimension.” 


Each "element" is actually an ordered tuple. Function w_add only uses the 
first tuple of each n-tuple in in] and in2 to create the sum that is stored in 
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the first tuple of the corresponding element in out. For example, the first 
tuple of the first element of the first dimension of in] is added to the first 
tuple of the first element of the first dimension of in2 and the sum is stored 
in the first tuple of the first element of the first dimension of out. 


All waveforms must be valid, but the data type of the first tuples of each © 
waveform do not need to be the same. w_add performs the addition in 

double precision and coerces the results into the type of the out waveform 

array. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 
SEE ALSO 
Include files: 
spd.h 


wav.h 


BASIC FORMAT 


CALL bwadd(inZ, in2Z, out%, statusZ) 


Where: 


inZo 
integer identifying one input waveform. © 


in2% 
integer identifying the other input waveform. 


out% 
integer identifying the output waveform that will hold the sums of ele- 
ments of inJ and in2. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
OF 
#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM *inl, *in2, *out; 
Status = w_add(inl, in2, &out); 


status = wf_tunits(tup_units(in1,0),COPY,0,out); /* copy units */ 
Status = wf_dunits(dim_units(in1,0),COPY,0,out); 


dim_scale(out,0) = dim _scale(inl1,0); 
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BASIC: 


* SINCLUDE: ‘\tek\spd\include\tekspd.bi’ 
inlZ = 1: in2Z% = 2: out% =3 


call bwadd(inl%, in2%, out%, statusZ) 


" set units and scaling for waveform outZ 
brtupunits(in1%,0,inVunitsS,inVlen%,status2Z) 
brdimunits(in1Z,0,inHunitsS, inHlenZ,status2Z) 


bwftunits(inVunitsS,0%,outZ,statusZ) 
bwfdunits(inHunitsS,0Z,outZ,statusZ) 


brdimscale(in1Z,0,hsf#, status2Z) 
bwdimscale(outZ,0,hsf#, statusZ) 
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NAME 
w_decimate 


PURPOSE 
Decimates a waveform by an integer factor. © 


SYNOPSIS 
#include “tekspd.h" 


ERRORTY PE 
w_decimate(in_wf, dec_factor, first_el, out_wf) 


WAVEFORM *in wf, *out_wf; 
int dec factor; 
long first_el; 


Where: 
in_wf: 
pointer to the input waveform to be decimated. 
dec_factor: 
integer factor in which to decimate waveform. 
first_el: 
index of the first element in the waveform to be output. } 
out wy: 
pointer to the output waveform that will hold the results of the decima- 
tion. 


DESCRIPTION 


w_decimate copies every dec_factor element in in_wf starting with first_e/ to 
out _wf. All intervening elements in in_wf are skipped. 


To contain the entire result of the decimation, the output waveform must 
have a length equal to or greater than (length of in_wf - first_el) / dec_fac- 
tor. If the output waveform has a length less than this, it is filled with as 
many data elements as possible, starting with first_el. 


All waveforms must be valid and the same waveform can be used for both 
input and output. The data type of each waveform need not be the same. 


The type of each waveform is assumed to be that of the first tuple of the ele- 
ments in its first dimension, and only the first tuple in each element of the 
first dimension of each waveform is used in the computations. 


w_decimate returns an error code (as defined in the spd.h include file) in- _ 
dicating whether or not it was able to perform correctly. A FATAL error is 
issued if: 


in_wf or out_wf is not valid or NIL. 
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first_el is less than zero or greater than or equal the length of in_ wf. 
length of in_wf - first_el less than dec_factor. 


SEE ALSO 
Include files: 
wav.h 
spd.h 
BASIC FORMAT 


CALL bwdecimate( inwf%, decfactorZ, firstel&, outwf%, status2) 


Where: 
inwfQo: 


integer identifying the input waveform to be decimated. 
decfactor%: 
integer factor in which to decimate waveform. 
firstel&: 
index of the first element in the waveform to be output. 
outwf%: 
integer identifying the output waveform that will hold the results of the 
decimation. 


status%: 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
C: 


#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM *in, *out; 
int factor; 


factor = 4; 
status = w_decimate(in, factor, 0, &out); 


status = wf_tunits(tup_units(in,0),COPY,0,out); /* copy units */ 
status = wf_dunits(dim_units(in,0),COPY,0,out); 


dim_scale(out,0) = dim_scale(in,0) * factor; 


BASIC: 


' SINCLUDE: '\tek\spd\include\tekspd.bi’ 
inlZ = 1: in2Z% = 2: outzZ #3 
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factor% = 4 

call bwdecimate(inz, factor%, 0, outZ, status2Z) 

’ set units and scaling for waveform outZ 
brtupunits(inZ,0,inVunitsS,inVlenZ,statusZ) © 
brdimunits(inZ,0,inHunitsS,inHlenZ,statusZ) 


bwftunits(inVunitsS ,0Z,out%, statusZ) 
bwfdunits(inHunitsS,02%,out%, statusZ) 


brdimscale(inz,0,hsf#, status2Z) 
bwdimscale(out%,0,hsf# * factor%Z,statusZ) 
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NAME 
w_div 
PURPOSE 


Divides elements of the first n-dimensional waveform array by elements of 
the second n-dimensional waveform array and places the quotients in an n- 
dimensional output waveform array. 


SYNOPSIS 
#include “tekspd.h" 


ERRORTYPE 
w_div(inl, in2, out) 


WAVEFORM *inl, *in2, *out; 


Where: 
ind: 
pointer to one input waveform. 
in2: 
pointer to the other input waveform. 
out: 


pointer to the output waveform that will hold the quotients of elements 
of in] and in2. 


DESCRIPTION 


The least number of dimensions and the least number of elements in any 
given dimension on inJ or in2 or out are used as the basis for determining 
the extent to which out is "filled" with quotients. For example, if in] has 4 
elements along its first dimension, in2 has 2 elements along its first dimen- 
sion and out has 3 elements along its first dimension, the first 2 elements 
along the first dimension of out will be “filled” with quotients. 


The following examples should make this clear: 


inl in2 out Portion of out holding 
quotients 

4x4x3 3x4x4 2x2 2x2 | 

1x4x1 4x1x1 1x1x4 1x1x1 (or 1 element) 

2x2x2 2x2x2 4x4 2x2 

4x4x4 4x4x4 4x4x4 4x4x4 


where 4x4x3 means "4 elements along the first dimension, 4 elements along 
the second dimension, and 3 elements along the third dimension.” 
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Each "element" is actually an ordered n-tuple. Function w_div only uses the 
first tuple of each n-tuple in in] and in2 to create the quotient that is stored 
in the first tuple of the corresponding element out. For example, the first 
tuple of the first element of the first dimension of inJ is divided by the first 
tuple of the first element of the first dimension of in2 and the quotient is -_ 
stored in the first tuple of the first element of the first dinension of out. 

All waveforms must be valid, but the data type of the first tuples of each 
waveform do not need to be the same. w_div performs the division in 
double precision and coerces the results into the type of the out waveform 
array. 

This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 
spd.h 
wav.h 
BASIC FORMAT 


CALL bwdiv(inlZ, in2Z%, out%, statusZ) 


Where: 
inl% 
integer indentifying one input waveform. 


in2% 
integer identifying the other input waveform. 


outZo 
integer identifying the output waveform that will hold the quotients of 
elements of ind and in2. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
C 
#include “tekspd.h" 


ERRORTYPE status; 
WAVEFORM *inl, *in2, *out; 


char outunits [80]; © 
status = w_div(inl, in2, &out); 

strepy(outunits,tup_units(in1,0)); 7/* V units from inl */ 
strceat(outunits," / "); 

strcat(outunits,tup_units(in2,0)); /* Vounits from in2 */ 


8-214 Signal Processing & Display 


Signal Processing 


w div 


Status = wf _tunits(outunits,COPY,0,out); /* insert new units */ 
status = wf_dunits(dim_units(inl,0),COPY,0,out); 


dim_scale(out,0) = dim scale(in1,0); 


BASIC: 


' SINCLUDE: '\tek\spd\include\tekspd.bi’ 
inlZ% = 1: in2Z% = 2: outZ =3 


call bwdiv(in1%, in2%, outZ, status2Z) 


" set units and scaling for waveform outZ 

brtupunits(in1%,0,inlunitsS,inllenZ,status2Z) 
brtupunits(in22,0,in2unitsS,in2lenZ,statusZ) 
brdimunits(in12,0,inHunitsS, inHlenZ,status2Z) 


bwftunits(inlunitsSt" / "+in2units$,02%,out%,statusZ) 
bwfdunits(inHunitsS,0%,out%, statusZ) 


brdimscale(in1Z,0,hsf#,status2Z) 
bwdimscale(outZ,0,hsf#,status2Z) 
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NAME 
w_exp 
PURPOSE 


Raises base to the power specified by each element of one waveform and 
stores the results in the corresponding elements of another waveform. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTY PE 
w_exp(in, base, out) 


WAVEFORM *in, *out; 
double base; 


Where: 
In: 
pointer to the waveform containing input data. 


out: 
pointer to the waveform containing data after power is evaluated. 


base: 
base that is raised by the input elements to give the output elements. 


DESCRIPTION 


w_exp takes base and raises it to the power specified by the elements in the 
array pointed to by in and stores the result in the corresponding elements in 
the waveform pointed to by out, or 


out = base” 


Both waveforms must be valid. If the two waveforms are the same, w_exp 
overwrites the input waveform. If the waveform arrays have different dimen- 
sions, the output waveform array is valid only to the smaller dimension. If 
for any dimension the arrays have different lengths, the output waveform is 
valid only for the shorter length in that dimension. 


Data type information is taken from the first tuple of both the input and 
Output waveform arrays. Information is taken from the first tuple of both 
the input and output waveform arrays. Information is taken from the first 
tuple of the input array and stored in the first tuple of the output array. If 
the base is negative, the absolute value is taken, a warning error message 1s 
sent to the user, and calculation continues. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 
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SEE ALSO 
Include files: 


wav.h 
spd.h 


BASIC FORMAT 


CALL bwexp(inz, base#, outZ, status2Z) 


Where: 
inZo 
integer identifying the waveform containing input data. 


base# 
base that is raised by the input elements to give the output elements. 


outT%o 
integer identifying the waveform containing data after power is 
evaluated. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
c 
#include “tekspd.h" 
ERRORTYPE status; 


WAVEFORM *in, *out; 
double base; 


base = 2.71828; 

status = w_exp(in, base, &out); 

Status = wf_dunits(dim_units(in,0),COPY,0,out); 
dim_scale(out,0) = dim_scale(in,0); 


BASIC: 


' SINCLUDE: ‘'\tek\spd\ineclude\tekspd.bi’ 
ing = 1: outZ% = 2 


call bwexp(inZ, 2.71828, out%, statusZ) 
* set units and scaling for waveform outZ 


brdimunits(inz,0,inHunitsS, inHlenZ,statusZ) 
bwfdunits(inHunitsS,0%,outZ,status2Z) 


brdimscale(inz,0,hsf#, statusZ) 
bwdimscale(outZ,0,hsf#,statusZ) 
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NAME 
w_interp 


PURPOSE © 
Interpolates a uniformly sampled waveform by an integer factor. 
SYNOPSIS 


#include "tekspd.h”" 


ERRORTYPE 
w_interp(in_ wf, flag, factor, filt_lens, arr, eoaa, out _wf) 


WAVEFORM *in_wf, *out_wf; 
int flag, factor, filt_len, eoaa; 
double “arr; 


Where: 

in_wf: 
pointer to the input waveform. 

flag: 
type of interpolation filter to use. It should be LINEAR, SINC, or 
USER_FILT. 


factor: @ 
interpolation factor. It must be at least 2. 


filt_len: 
length of the interpolation filter. It should be an odd number that is at 
least 3 if flag is SINC or USER_FILT. This parameter is ignored if flag 
is LINEAR. 


air, 
double array needed to hold the interpolation filter coefficients. The 
setup and use of this array is determined by flag. 


If flag = LINEAR, then linear interpolator coefficients are generated 
by w_interp and stored in this array. It should be at least (factor - 1) ele- 
ments long. 


If flag = SINC, then sin(x)/x type interpolation filter coefficients are 
generated by w_interp and stored in this array. It should be at least 
(filt_len + 1)/2 elements long. 


If flag = USER_FILT, then arr/{] must contain the coefficients of the 

user defined Finite Impulse Response (FIR) interpolation filter prior to 

calling w_iterp. This filter is assumed to have even symmetry, and to ©} 
have an odd length. Hence, the coefficients passed in through arr/] 

should contain the filter coefficients indexed from 0 through (filt_len - 

1)/2 and arr[] must be at least (filt_len + 1)/2 elements long. 
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eoaa: 
End-of-array algorithm to use. Accepted values are EA REPEAT, 
EA_BOUNCE, EA INVERT, EA WARP, and EA ZERO. 


out wf: 


@ Pointer to the output waveform. 


DESCRIPTION 


w_interp operates only on the first dimension and the first tuple of the input 
waveform. 


The interpolation process can be viewed as convolving as FIR interpolation 
filter with the input waveform, modified by inserting (factor - 1) zeros be- 
tween every pair of input samples. Within this framework, w_interp provides 
the option of using different kinds of interpolation filters by setting flag to 
one of LINEAR, SINC,. or USER_FILT. 


If flag = LINEAR, then linear interpolation is provided by internally 
generating the filter coefficients, and implementing the convolution in an ef- 
ficient manner. 


If flag = SINC, then the filter kernel of length fi/t_len generated internally 
is a sin(x)/x type. The basic filter kernel of this type needed for interpola- 
tion by a factor of factor is 


sin | 27 
factor 


nt 


factor 


This is multiplied by a Hamming window to reduce the effects of truncating 
this kernel to a finite length. The above kernel does not preserve the DC 
value of the input waveform. Hence, the kernel is further modified using 
suitable normalization of the coefficients in order to preserve the DC value. 
Since the filter is symmetric, arr[] need be only of length (fi/t_len + 1)/2. In 
order to ensure that there is no half sample delay in the interpolated 
waveform, filt_len must be an odd number. The convolution operation is 
then implemented in an efficient manner to obtain the interpolated 
waveform. 


If flag = USER_FILT, then the interpolation is done by using an user 
defined interpolation filter whose coefficients must be available in arr/]. 
The filter is assumed to be a Finite Impulse Response filter with even sym- 
metry, and odd length filt_len. This ensures that the filter is linear phase, 
and that it does not introduce half sample delays in the interpolated 
waveform. Due to the symmetry of the filter, arr{] should contain only the 
(filt_len + 1)/2 filter coefficients indexed from 0 through (filt_len - 1)/2. 


The values for eoaa should be one of the values described on page 8-2. 
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w_interp issues FATAL errors in the following situations: 


If either or both of the waveform pointers, in_wf and out_wf are not 
valid. 


If the iterpolation factor, factor, is less than 2. 


If the output waveform array is not large enough to hold the interpo- 
lated data. Its length must be at least the product of factor and the 
length of the input waveform array. 


If flag = USER_FILT, implying that the filter is user defined, and the 
length of the filter, fi/t_len is less than 3 or is an even number. 


If flag = SINC, and filt_len is less than 3. 


If flag = SINC or USER _FILT, then w_interp needs to allocate tem- 
porary double memory locations approximately equal to the length of 
in_wf plus filt_len. If this memory is not available, a FATAL error is is- 
sued. 


A number of other default actions are taken by w_interp when the validity 
of input parameters is less critical. The user is issued a WARNing error 
about the action taken. Specifically, if 


flag is not one of LINEAR, SINC, or USER_FILT, then it is set to 
LINEAR. 


flag = SINC, and filt_len is an even number greater than 3, then filt_len 
is decremented by 1 to make it odd. 


eoaa is not a valid value, then it is set to EA REPEAT. 
This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to execute correctly. 
SEE ALSO 
Include files: 


wav.h 
spd.h 
sp.h 


Signal processing functions: 
eq fir 
pt_interp 
BASIC FORMAT 


CALL bwinterp(inwf%, flagz, factorZ, filtlenz, arr#(0), eoaaz, 
outwfZ, statusZ) 


Where: 
inwfTZo 


integer identifying the input waveform. 
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flag% 
type of interpolation filter to use. Use the pre-defined constants 
LINEAR%, SINC%, or USERFILT% 


factor% 
interpolation factor. It must be at least 2. 

filtlen% 
length of the interpolation filter. It should be an odd number that is at 
least 3 if flag is SINC% or USERFILT%. This parameter is ignored if 
flag is LINEAR%. 

arr# (0) 
double array needed to hold the interpolation filter coefficients. The 
setup and use of this array is determined by flag. 


If flag = LINEAR%, then linear interpolator coefficients are generated 
by w_interp and stored in this array. It should be at least (factor - 1) ele- 
ments long. 


If flag = SINC%, then sin(x)/x type interpolation filter coefficients are 
generated by w_interp and stored in this array. It should be at least 
(filt_len + 1)/2 elements long. 


If flag = USERFLT%, then arr[] must contain the coefficients of the 
user defined Finite Impulse Response (FIR) interpolation filter prior to 
calling w_interp. This filter is assumed to have even symmetry, and to 
have an odd length. Hence, the coefficients passed in through arr[] 
Should contain the filter coefficients indexed from 0 through (filt_len - 
1)/2 elements long. 


eoaa% 
end-of-array algorithm. Should be one of the pre-defined constants 
REPEAT%, BOUNCE%, INVERT%, WRAP%, or ZERO%. 
outwf% 
integer identifying the output waveform. 
status % 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
GS 
#include "tekspd.h" 


ERRORTYPE status; 
WAVEFORM *in, *out; 


int factor; 
@ double arr(3]; 


factor = 4; 


Status = w_interp(in, LINEAR, factor, 3, arr, EA_REPEAT, 4&out); 


Signal Processing & Display 8-22] 


Signal Processing 


w_interp 


status = wf_tunits(tup_units(in,0),COPY,0,out); /* copy units w/ 
status = wf _dunits(dim_units(in,0),COPY,0,out); 


dim_scale(out,0) = dim_scale(in,0) / factor; 


BASIC: © 


'" SINCLUDE: ‘\tek\spd\include\tekspd.bi’ 
inlZ = 1: in2% = 2: out% =3 

DIM arr#(3) 

factorz = 4 


call bwinterp(inz%, LINEARZ, factor%, 3, arr#(0), REPEAT%, outZ, 
statusZ) 


' set units and scaling for waveform outZ 
brtupunits(inZ,0,inVunitsS,inVlenZ,status2Z) 
brdimunits(inZ,0,inHunitsS, inHlenZ,statusZ) 


bwftunits(inVunitsS,02%,outZ%,statusZ) 
bwfdunits(inHunitsS , 0%, outZ,statusZ) 


brdimscale(inz,0,hsf#,statusZ) 
bwdimscale(out%,0,hsf# / factor%,status2Z) 
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NAME 


w_log 


PURPOSE 


Takes a logarithm of a waveform and stores the result in another waveform. 
SYNOPSIS 
#include "“tekspd.h”" 


ERRORTYPE 
w_log(in, base, out) 


WAVEFORM *in, *out; 
double base; 


Where: 
In: 
pointer to the waveform containing input data. 


out: 
pointer to the waveform containing data after the logarithm is taken. 


base: 
base by which the logarithm of the input is taken to give the output. 


DESCRIPTION 


w_log takes the log base base of the array pointed to by in and stores the 
result in the array pointed to by out, or 


out = lOpase(in) 
Both waveforms must be valid. The base must not be one, negative one, or 
zero. If it is, w_/og returns a FATAL error and does not execute. If the two 
waveforms are the same, w_/og overwrites the input waveform. If the 
waveform arrays have different dimensions, the output waveform array is 
valid only to the smaller number of dimensions. If for any dimension the ar- 


rays have different lengths, the output waveform is valid only for the 
shorter length in that dimension. 


Data type information is taken from the first tuple of both the input and 
Output waveform arrays. Data is taken from the first tuple of the input 
array and stored in the first tuple of the output array. If the base is nega- 
tive, the absolute value is taken and a WARNing error issued. If a number 
in the input waveform is negative, the absolute value is taken and a 
WARNing error issued. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 
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SEE ALSO 
Include files: 


wav.h 
spd.h 
BASIC FORMAT 


CALL bwlog(inZ, base#, outZ, status2Z) 


Where: 
ino 
integer identifying the waveform containing input data. 


base# 
base by which the logarithm of the input is taken to give the output. 


out% 
integer identifying the waveform containing data after the logarithm is 
taken. 


status To 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE © 
i 


#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM *in, *out; 
double base; 


base = 2.0; 

status = w_log(in, base, &out); 

status = wf_dunits(dim_units(in,0),COPY,0,out); 
dim_scale(out,0) = dim_scale(in,0); 

BASIC: 


" SINCLUDE: '\tek\spd\include\tekspd.bi' 
inZ = 1: outZ% = 2 


call bwlog(inl%, 2.0, out%Z, statusZ) 
* set units and scaling for waveform outz & 
brdimunits(inZ,0,inHunitsS,inHlenZ,statusZ) 


bwfdunits (inHunits$, 0%, outZ, statusZ) 


brdimscale(inz,0,hsf#, statuszZ) 
bwdimscale(out%,0,hsf#, statusZ) 
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NAME 
w_max 
PURPOSE 


This function compares corresponding elements of two n-dimensional input 
waveform arrays and places the maximum values in an n-dimensional out- 
put waveform array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
w_max (inl, in2, out) 


WAVEFORM *inl, *in2, *out; 


Where: 
ind: 
pointer to one input waveform 
In2: 
pointer to the other input waveform 
out: 


pointer to the output waveform which will hold the maximum values of 
elements of in and in2 


DESCRIPTION 


The least number of dimensions and the least number of elements in any 
given dimension of inJ or in2 or out are used as the basis for determining 
the extent to which out is "filled" with maximums. For example, if in] has 4 
elements along its first dimension, in2 has 2 elements along its first dimen- 
sion and out has 3 elements along its first dimension, the first 2 elements 
along the first dimension of out will be "filled" with the maximum values. 


The following examples should make this clear: 


inl in2 out Portion of out holding 
maamums 

4x4x3 3x4x4 2x2 2x2 

2xx2x2 2x2x2 4x4 2x2 

4x4x4 4x4x4 4x4x4 4x4x4 


where 4x4x3 means "4 elements along the first dimension, 4 elements along 
the second dimension, and 3 elements along the third dimension." 


Each "element" is actually an ordered n-tuple. Function w_max only uses 
the first tuple of each n-tuple in ind and in2 to determine the maximum 
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value which is stored in the first tuple of the corresponding element in out. 
The first tuple of the first element of the first dimension of inJ is added to 
the first tuple of the first element of the first dimension of in2 and the maxi- 
mum is stored in the first tuple of the first element of the first dimension of 
out, etc. 


All waveforms must be valid, but the data type of the first tuples of each 
waveform do not need to be the same. w_max performs the comparison in 
double precision and coerces the results into the tuple of the out waveform 
array. 


w_max returns an error code as defined in spd.h indicating whether it was 
able to perform correctly or not. 
SEE ALSO 
spd.h 
wav.h 


BASIC FORMAT 


CALL bwmax(inlZ, in2Z, out2, statusZ) 


Where: 


inl% 


integer identifying one input waveform. 
in2% 
integer identifying the other input waveform. 


outZ% 
integer identifying the output waveform which will hold the maximum 
values of elements of in] and in2. 


status% 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
ci 
#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM *inl, *in2, *out; 
Status = w_max(inl, in2, &out); 


status = wf_tunits(tup_units(inl,0),COPY,0,out); /* copy units */ 
status = wf_dunits(dim_units(in1,0),COPY,0,out); 


dim_scale(out,0) = dim_scale(in1,0); 
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BASIC: 


" SINCLUDE: '\tek\spd\include\tekspd.bi’ 
inlZ = 1: in2% = 2: out% =3 


call bwmax(inlZ%, in2%, out%, statusZ) 


* set units and scaling for waveform outZ 
brtupunits(in1%,0,inVunits$,inVlenZ, status2Z) 
brdimunits(in12Z,0,inHunitsS, inHlenZ, status2Z) 


bwftunits(inVunitsS,0%,outZ,statusZ) 
bwfdunits (inHunitsS , 02, outZ%, status2Z) 


brdimscale(in1Z,0,hsf#, status2Z) 
bwdimscale(outz,0,hsf#, status2Z) 


Signal Processing & Display 8-227 


Signal Processing 
w min 


NAME 


w_min 


PURPOSE 
This function compares corresponding elements of two n-dimensional input ae 
waveform arrays and places the minimum values in an n-dimensional out- 
put waveform array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
w_min (inl, in2, out) 


WAVEFORM *inl, *in2, *out; 


Where: 
ind: 
pointer to one input waveform 
in2: 
pointer to the other input waveform 
out: 


pointer to the output waveform which will hold the minimum values of 
elements of in] and in2 


DESCRIPTION 


The least number of dimensions and the least number of elements in any 
given dimension of in or in2 or out are used as the basis for determining 
the extent to which out is "filled" with minimums. For example, if inJ has 4 
elements along its first dimension, m2 has 2 elements along its first dimen- 
sion and out has 3 elements along its first dimension, the first 2 elements 
along the first dimension of out will be "filled" with the minimum values. 


The following examples should make this clear: 


inl in2 out Portion of out holding 
minimums 

4x4x3 3x4x4 2x2 2x2 

1x4x1 4x1x1 1x1x4 1x1x1 (or 1 element) 

2x2x2 2x2x2 4x4 2x2 


4x4x4 4x4x4 4x4x4 4xdx4 @& 


where 4x4x3 means "4 elements along the first dimension, 4 elements along 
the second dimension, and 3 elements along the third dimension" 
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Each “element” is actually an ordered n-tuple. Function w_min only uses 
the first tuple of each n-tuple in in] and in2 to determine the minimum 
value which is stored in the first tuple of the corresponding element in out. 
The first tuple of the first element of the first dimension of inJ is added to 
the first tuple of the first element of the first dimension of in2 and the mini- 
mum is stored in the first tuple of the first element of the first dimension of 
out, etc. | 


All waveforms must be valid, but the data type of the first tuples of each 
waveform do not need to be the same. w_min performs the comparison in 
double precision and coerces the results into the type of the out waveform 
array. 


w_min returns an error code as defined in spd.h indicating whether it was 
able to perform correctly or not. 


SEE ALSO 


spd.h 
wav.h 


BASIC FORMAT 


CALL bwmin(in1Z%, in2%, out%, statusZ) 


Where: 


inl% 
integer identifying one input waveform. 


in2% 
integer identifying the other input waveform. 


out% 
integer identifying the output waveform which will hold the minimum 
values of elements of in] and in2. 


status To | 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 


_ 

#include "tekspd.h" 
ERRORTYPE status; 

WAVEFORM *inl, *in2, *out; 


status = wmin(inl, in2, &out); 


status = wf_tunits(tup_units(in1,0),COPY,0,out); /* copy units */ 
status = wf_dunits(dim_units(in1,0),COPY,0,out); 


dim_scale(out,0) = dim_scale(in1,0); 
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BASIC: 


' SINCLUDE: ‘\tek\spd\include\tekspd.bi’ 
inlZ = 1: in2Z% = 2: outZ =3 


call bwmin(inlZ, in2Z, out%Z, status2Z) r 


' set units and scaling for waveform outZ 
brtupunits(in12Z,0,inVunits$,inVlenZ,status2Z) 
brdimunits(in1%,0,inHunitsS, inHlenZ,status2Z) 


bwftunits(inVunitsS ,0%,out%, statusZ) 
bwfdunits(inHunitsS ,02%, outZ, statusZ) 


brdimscale(in1Z,0,hsf#, status2Z) 
bwdimscale(out2Z,0,hsf#,status2Z) 
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NAME 


w_mult 


PURPOSE 
Multiplies corresponding elements of two n-dimensional input waveform ar- 
rays and places the products in an n-dimensional output waveform array. 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
w_mult(inl, in2, out) 


WAVEFORM *inl, *in2, *out; 


Where: 
ind: 
pointer to one input waveform. 
ind: 
pointer to the other input waveform. 
out: 


pointer to the output waveform that will hold the products of elements 
of in] and in2. 


DESCRIPTION 


The least number of dimensions and the least number of elements in any 
given dimension of ind or in2 or out are used as the basis for determining 
the extent to which out is "filled" with products. For example, if in] has 4 
elements along its first dimension, in2 has 2 elements along its first dimen- 
sion and out has 3 elements along its first dimension, the first 2 elements 
along the first dimension of out will be "filled" with products. 


The following examples should make this clear: 


inl in2 out Portion of out holding 
products 

4x4x3 3x4x4 2x2 2x2 

1x4x1 4x1x1 1x1x4 1x1x1 (or 1 element) 

2x2x2 2x2x2 4x4 2x2 

4x4x4 4x4x4 4x4x4 4x4x4 


where 4x4x3 means "4 elements along the first dimension, 4 elements along 
the second dimension, and 3 elements along the third dimension." 


Each "element" is actually an ordered n-tuple. Function w_mult only uses 
the first tuple of each n-tuple in in] and in2 to create the product that is 
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stored in the first tuple of the corresponding element in out. For example, 

the first tuple of the first element of the first dimension of in] is multipled 

by the first tuple of the first element of the first dimension of in2 and the 

product is stored in the first tuple of the first element of the first dimension ® 
of out. 


All waveforms must be valid, but the data type of the first tuples of each 
waveform do not need to be the same. w_mult performs the multiplication 
in double precision and coerces the results into the tuple of the out 
waveform array. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 
SEE ALSO 
Include files: 
spd.h 


wav.h 


BASIC FORMAT 


CALL bwmult(inlZ, in2%, outZ, statusZ) 


Where: 


inl% & 
integer identifying one input waveform. 


in2% 
integer identifying the other input waveform. 

out% 
integer identifying the output waveform that wil hold the products of 
elements of in and in2. 

status Zo 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
ce 
#include "“tekspd.h" 


ERRORTYPE status; 
WAVEFORM *inl, *in2, *out; 


char outunits[80]; 

status = w_mult(inl, in2, &out); - 
strcpy(outunits,tup units(inl,0)); /* V units from inl */ 
streat(outunits,"” * "); 

strcat(outunits,tup_units(in2,0)); /* V units from in2 */ 


status = wf_tunits(outunits,COPY,0,out); /* insert new units */ 
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status = wf_dunits(dim_units(in1,0),COPY,0,out); 
dim_scale(out,0) = dim_scale(inl,0); 


@ BASIC: 


' SINCLUDE: '\tek\spd\include\tekspd.bi’ 
inlZ = 1: in2% = 2: outZ =3 


call bwmult(inlZ, in2Z, out%, statusZ) 

* set units and scaling for waveform outZ 
brtupunits(in1Z,0,inlunitsS,inllen%,statusZ) 
brtupunits(in2%,0,in2units$,in2len%,status2) | 
brdimunits(in1Z,0,inHunitsS, inHlenZ,status2Z) 


bwftunits(inlunits$+" * "+in2unitsS,0Z,outZ,status2Z) 
bwfdunits(inHunitsS, 0%, outZ, statusZ) 


brdimscale(in1Z,0,hsf#,statusZ) 
bwdimscale(outZ,0,hsf#, statusZ) 
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NAME 
w_power 


PURPOSE 
Raises each element of one waveform to a specified power and stores the 
results in the corresponding elements of another waveform. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
w_power(in, exp, out) 


WAVEFORM *in, *out; 
double exp; 
Where: 
in: 
pointer to the waveform containing the input data. 
out: 
pointer to the waveform containing the data after power is evaluated. 
=e e e es e 
exponent to which each element of the input waveform is raised. _ 
DESCRIPTION 


w_power takes each element of the waveform pointed to by in and raises it 
to the power specified by exp and stores the result in the corresponding ele- 
ment of the waveform pointed to by out, or 


out = inOP 
Both waveforms must be valid. If the two waveforms are the same, w_power 
overwrites the input waveform. If the waveform arrays have different dimen- 
sions, the output waveform array is valid only to the smaller dimension. If 
for any dimension, the arrays have different lengths, the output waveform is 
valid only for the shorter length in that dimension. 


Data type information is taken from the first tuple of both the input and 
Output waveform arrays. Information is taken from the first tuple of the 
input array and stored in the first tuple of the output array. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. ®@ 


SEE ALSO 
Include files: 


wav.h 
spd.h 
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BASIC FORMAT 


CALL bwpower(inZ, exp#, out%, statusZ) 


Where: 
in% 

integer identifying the waveform containing the input data. 
exp# 

exponent to which each element of the input waveform is raised. 
out% 


integer identifying the waveform containing the data after power is 
evaluated. 


status% 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 


C: 


#include "tekspd.h”" 
ERRORTYPE status; 
WAVEFORM *in, *out; 
double exp; 

char outunits [80]; 


exp = 3.0; 
status = w_power(in, exp, &out); 


strepy(outunits,tup_units(in,0)); /* V units from in */ 
strcat(outunits,”" "); 

strcat(outunits,tup_units(in,0)); 

strcat(outunits,” "); 

strcat(outunits,tup_units(in,0)); 


Status = wf _tunits(outunits,COPY,0,out); /* insert V units */ 
Status = wf_dunits(dim_units(in,0), COPY,0,out); 


dim_scale(out,0) = dim _scale(in,0); 
BASIC: 

' SINCLUDE: '\tek\spd\include\tekspd.bi' 
inlZ = 1: outZ =2 

exp# = 3.0 


call bfconv(inZ%, exp#, out%, statusZ) 


’ set units and scaling for waveform outZ 
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brtupunits(inZ,0,VS,lenZ,status2Z) 
bwftunits(VSt" "+VS+" "+VS, 0Z, outZ, statusZ) 


brdimunits(inz%,0,HS,inHlenZ,status2Z) 
bwfdunits(HS,0%,outZ, status2Z) 


brdimscale(inz,0,hsf#,status2Z) 
bwdimscale(outZ,0,hsf#,status2Z) 
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NAME 
w_ sqrt 
PURPOSE 


Takes the square root of a waveform and stores the result in another 
waveform. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
w_sqrt(in, out) 


WAVEFORM *in, *out; 


Where: 
In: 
pointer to the waveform containing input data. 


out: 
pointer to the waveform containing data after square root taken. 


DESCRIPTION 


@ w_sqrt takes the square root of the waveform pointed to by im and stores 
the result in the waveform pointed to by out. 


Both waveforms must be valid. If the two waveforms are the same, w_sqrt 
overwrites the input waveform. If the waveform arrays have different dimen- 
sions, the output waveform array is valid only to the smaller dimension. If 
for any dimension the arrays have different lengths, the output waveform is 
valid only for the shorter length in that dimension. 


Data type information is taken from the first tuple of both the input and 


output waveform arrays. Data is taken from the first tuple of the input 


array and stored in the first tuple of the output array. If a number in the 
input waveform is negative, the absolute value is taken, a WARNing error 
message is sent to the user, and calculation continues. 


The function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 

SEE ALSO 
Include files: 


S spd.h 
wav.h 
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BASIC FORMAT 


CALL bwsqrt(inZ, outZ, statusZ) 


Where: ® 
ino 


integer identifying the waveform containing input data. 


outTZo 
integer identifying the waveform containing data after square root is 
taken. 


status Zo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
C: 
#include "“tekspd.h" 
ERRORTYPE status; 


WAVEFORM *in, *out; 
char outunits [80]; 


status = w_sqrt(in, &out); © 
strepy(outunits,tup_units(in,0)); /* V units from in */ 


strceat(outunits,” ** 1/2"); 


Status = wf_tunits(outunits,COPY,0,out); /* insert V units */ 
status = wf_dunits(dim_units(in,0), COPY,0,out); 


dim_scale(out,0) = dim_scale(in,0); 
BASIC: 

' SINCLUDE: ‘*\tek\spd\include\tekspd.bi' 
inlZ = 1: outZ =2 

exp# = 3.0 

call bfconv(inZ, exp#, out%, status7Z) 


" set units and scaling for waveform outZ 
brtupunits(in%,0,V$,len%, statusZ) 


bwftunits(VSt+" ** 1/2", 0%, out%, statusZ) 


brdimunits(inZ%,0,HS,inHlenZ,statusZ) 
bwfdunits(HS,02Z,out%, statusZ) 


brdimscale(inz,0,hsf#,statusZ) 
bwdimscale(outZ,0,hsf#, statusZ) 
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NAME 


w_sub 


PURPOSE 


Subtracts elements of the second n-dimensional waveform array from ele- 
ments of the first n-dimensional waveform array and places the differences 
in an n-dimensional output waveform array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
w_sub(inl, in2, out) 


WAVEFORM *inl, *in2, *out; 


Where: 
inl: 
pointer to one input waveform. 
ind: 
pointer to the other input waveform. 


oul: 


pointer to the output waveform which will hold the differences of ele- 
ments of in] and in2. 


DESCRIPTION 


The least number of dimensions and the least number of elements in any 
given dimension of in1 or in2 or out are used as the basis for determining 
the extent to which out is "filled" with differences. For example, if ind has 4 
elements along its first dimension, in2 has 2 elements along its first dimen- 
sion and out has 3 elements along its first dimension, the first 2 elements 
along the first dimension of out will be "filled" with differences. 


The following examples should make this clear: 


inl in2 out Portion of out holding 
differences 

4x4x3 3x4x4 2x2 2x2 

1x4x1 4x1x1 1x1x4 1x1x1 (or 1 element) 

2Xx2x2 2x2x2 4x4 ke 

4x4x4 4x4x4 4x4x4 4x4x4 


where 4x4x3 means "4 elements along the first dimension, 4 elements along 
the second dimension, and 3 elements along the third dimension." 
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Each "element" is actually an ordered n-tuple. Function w_sub only uses the 

first tuple of each n-tuple in in] and in2 to create the difference which is 

stored in the first tuple of the corresponding element in out. For example, 

the first tuple of the first element of the first dimension of in2 is subtracted 

from the first tuple of the first element of the first dimension of inJ and the 6 
difference is stored in the first tuple of the first element of the first dimen- 

sion of out. 


All waveforms must be valid, but the data tuple of the first tuples of each 
waveform do not need to be the same. w_sub performs the subtraction in 
double precision and coerces the results into the type of the out waveform 
array. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 
spd.h 
wav.h 


BASIC FORMAT 


CALL bwsub(inl%, in2Z, outZ, statusZ) 


Where: ® 


inl% 
integer identifying one input waveform. 


in2% 
integer identifying the other input waveform. 


out% 
integer identifying the output waveform which will hold the differences 
of elements of in] and in2. 


status To 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
Cc 


#include "tekspd.h" 
ERRORTYPE status; 


WAVEFORM *inl, *in2, *out; @ 


status = w_sub(inl, in2, &out); 


Status = wf_tunits(tup_units(in1,0),COPY,0,out); /* copy units */ 
status = wf _dunits(dim_units(in1,0),COPY,0,out); 
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dim_scale(out,0) = dim_scale(in1,0); 


BASIC: 


' SINCLUDE: '\tek\spd\include\tekspd.bi' 
inlZ = 1: in2Z = 2: outZ =3 


call bwsub(inlZ, in2%, outZ, statusZ) 


* set units and scaling for waveform out2Z 
brtupunits(in12Z,0,inlunits$,inllenZ, status2Z) 
bwftunits(inlunitsS,02Z,outZ,statusZ) 


brdimunits(in1Z,0,inHunitsS, inHlenZ,status2Z) 
bwfdunits(inHunitsS, 0Z,out2%,statusZ) 


brdimscale(in1Z%,0,hsf#, status2Z) 
bwdimscale(outZ,0,hsf#,statusZ) 
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NAME 
we_add 


PURPOSE 6 
Adds a constant to each element of an n-dimensional input waveform array 
and places the sums in an n-dimensional output waveform array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
we_add(in, const, out) 


WAVEFORM *in, *out; 
double const; 


Where: 
In: 
pointer to the input waveform. 


const: 
constant of type double. 


out 
pointer to the output waveform which will hold the sums of elements of a 
in with const. 


DESCRIPTION 


The least number of dimensions and the least number of elements in any 
given dimension of in or out are used as the basis for determining the ex- 
tent to which out is "filled" with sums. For example, if in has 4 elements 

along its first dimension and out has 2 elements along its first dimension, 


the first 2 elements along the first dimension of out will be "filled" with 
sums. 


The following examples should make this clear: 


in out Portion of out holding sums 
4x4x3 2x2 2x2 

1x4x1 1x1x4 1x1x1 (or 1 element) 

2x2x2 4x4 2x2 

4x4x4 4x4x4 4x4x4 


where 4x4x3 means "4 elements along the first dimension, 4 elements along 
the second dimension, and 3 elements along the third dimension." 
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Each “element” is actually an ordered n-tuple. Function we_add only uses 
the first tuple of each n-tuple in im to create the quotient that is stored in 
the first tuple of the corresponding element in out. For example, the first 
tuple of the first element of the first dimension of in is added to the con- 
stant and the sum is stored in the first tuple of the first element of the first 
dimension of out. 


All waveforms must be valid, but the data type of the first tuples of each 
waveform do not need to be the same. we_add performs the addition in 
double precision and coerces the results into the type of the out waveform 
array. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 

SEE ALSO 
Include files: 


wav.h 
spd.h 


BASIC FORMAT 
CALL bwediv(inZ%, const#, outZ, status2Z) 


Where: 


in 
integer identifying the input waveform. 


const# 
constant of type double. 


out% 
integer identifying the output waveform that will hold the quotients of 
elements of in with const. 


status 7 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
C: 
#include "tekspd.h" 
ERRORTYPE status; 


WAVEFORM *in, *out; 
double num; 


status = we_add(in, num, &out); 


status = wf_tunits(tup_units(in,0),COPY,0,out); /* copy units */ 
status = wf_dunits(dim_units(in,0),COPY,0,out); 
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dim _scale(out,0) = dim scale(in,0); 


BASIC: 
' SINCLUDE: '\tek\spd\include\tekspd.bi' - 
inZ = 1: outZ = 2 


call bwcadd(inl%, num#, out%, statusZ) 

‘ set units and scaling for waveform outZ 
brtupunits(inZ,0,inVunitsS,inVlenZ, statusZ) 
bwftunits(inVunitsS,0Z, outZ, statusZ) 


brdimunits(inZ,0,inHunitsS, inHlenZ,statusZ) 
bwfdunits(inHunitsS, 0%, outZ,statusZ) 


brdimscale(inZ,0,hsf#, status2Z) 
bwdimscale(outz,0,hsf#, status2Z) 
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NAME 


we _ div 
PURPOSE 
Divides each element of an n-dimensional input waveform array be a con- 
stant and places the quotients in an n-dimensional output waveform array. 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
we_div(in, const, out) 


WAVEFORM *in, *out; 
double const; 


Where: 
in: 
pointer to the input waveform. 


const: 
constant of type double. 


out: 
pointer to the output waveform that will hold the quotients of elements 
of in with const. 


DESCRIPTION 


The least number of dimensions and the least number of elements in any 
given dimension of im or out are used as the basis for determining the ex- 
tent to which out is "filled" with quotients. For example, if in has 4 elements 
along its first dimension and out has 2 elements along its first dimension, 
the first 2 elements along the first dimension of out will be filled” with 
quotients. 


The following examples should make this clear: 


in out Portion of out holding 
quotients 

4x4x3 2x2 2x2 

1x4x1 1x1x4 1x1x1 (or 1 element) 

2x2x2 4x4 2x2 

4x4x4 4x4x4 7 4x4x4 


where 4x4x3 means "4 elements along the first dimension, 4 elements along 
the second dimension, and 3 elements along the third dimension.” 
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Each “element” is actually an ordered n-tuple. Function we_div only uses 
the first tuple of each n-tuple in in to create the quotient that is stored in 
the first tuple of the corresponding element in out. For example, the first 
tuple of the first element of the first dimension of in is divided by the con- 
stant and the quotient is stored in the first tuple of the first element of the © 
first dimension of out. 

All waveforms must be valid, but the data type of the first tuples of each 
waveform do not need to be the same. wc_div performs the division in 
double precision and coerces the results into the type of the out waveform 
array. 

This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 
wav.h 
spd.h 
BASIC FORMAT 


CALL bwediv(inZ, const#, outZ, status2Z) 


Where: © 
inZ 


integer identifying the input waveform. 


const# 
constant of type double. 


out% 
integer identifying the output waveform that will hold the quotients of 
elements of in with const. 


status Yo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
C: 


#include "tekspd.h" 
ERRORTYPE status; 


WAVEFORM *in, *out; 
double num; in > 


status = we div(in, num, &out); 


status = wf_tunits(tup_units(in,0),COPY,0,out); /* copy units */ 
status = wf_dunits(dim_units(in,0),COPY,0,out); 
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dim_scale(out,0) = dim scale(in,0); 


BASIC: 


' SINCLUDE: '\tek\spd\include\tekspd.bi’ 
inz = 1: outZ = 2 


call bwediv(inZ, num#, outZ, statusZ) 


’ set units and scaling for waveform out%Z% 
brtupunits(inZ,0,inVunitsS, inVlen%Z, statusZ) 
bwftunits(inVunitsS, 0%, outZ,statusZ) 


brdimunits(inZ,0,inHunitsS, inHlen%Z, statusZ) 
bwfdunits(inHunitsS,0Z,out%,statusZ) 


brdimscale(inZ,0,hsf#,status2Z) 
bwdimscale(outZ,0,hsf#, status2Z) 
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NAME 


we_max 


PURPOSE _ 
This function compares a constant with each element of an n-dimensional 
input waveform array and places the maximum values in an n-dimensional 
Output waveform array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
we_max(in, const, out) 


WAVEFORM *in, *out; 
double const; 


Where: 
In: 
pointer to the input waveform 


CONST: 


constant of type double. 
wt @ 


pointer to the output waveform which will hold the maximums of ele- 
ments of im with const. 


DESCRIPTION 


The least number of dimensions and the least number of elements in any 
given dimension of im or out are used as the basis for determining the ex- 
tent to which out is "filled" with maximums. For example, if in has 4 ele- 


ments along its first dimension and out has 2 elements along its first 
dimension, the first 2 elements along the first dimension of out will be 
"filled" with maximums. 


The following examples should make this clear: 


in out Portion of out holding maamums 

4x4x3 2x2 2x2 

1x4x1 lx1x4 1x1x1 (or 1 element) 

2x22 4x4 2x2 @ 
4x4x4 4x4x4 4x4x4 


where 4x4x3 means "4 elements along the first dimension, 4 elements along 
the second dimension, and 3 elements along the third dimension.” 
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Each “element” is actually an ordered n-tuple. Function wce_max only uses 
the first tuple of each n-tuple in in to determine the maximum which is 
stored in the first tuple of the corresponding element in out. The first tuple 
of the first element of the first dimension of in is added to the constant and 

© the maximum is stored in the first tuple of the first element of the first 
dimension of out, etic. 


All waveforms must be valid, but the data type of the first tuples of each 
waveform do not need to be the same. wc_max performs the comparison in 
double precision and coerces the results into the type of the out waveform 
array. 


wce_max returns an error code as defined in spd.h indicating whether it was 
able to perform correctly or not. 
SEE ALSO 
wav.h 
spd.h 
BASIC FORMAT 


CALL bwemax(inZ, const#, out%Z, status2Z) 


Where: 


inZo 
integer identifying the input waveform. 


CONST # 
constant of the type double. 


outZo 
integer identifying the output waveform which will hold the maximums 
of elements of in with const. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
C: 


#include “tekspd.h” 
ERRORTYPE status; 
WAVEFORM *in, *out; 
double num; 


© status = wc_max(in, num, &out); 


status = wf _tunits(tup_units(in,0),COPY,0,out); /* copy units */ 
Status = wf _dunits(dim_units(in,0),COPY,0,out); 


dim_scale(out,0) = dim_scale(in,0); 
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BASIC: 

'" SINCLUDE: '\tek\spd\include\tekspd.bi’ 

int = 1: outZ = 2 a 
call bwemax(inZ, num#, out%Z, statusZ) 

‘ set units and scaling for waveform out2Z 
brtupunits(inZ,0,inVunitsS,inVlenZ,status2Z) 


bwftunits(inVunitsS,02%,out%, status2Z) 


brdimunits(inZ,0,inHunitsS, inHlenZ, statusZ) 
bwfdunits(inHunitsS ,0%,outZ,status2Z) 


brdimscale(inz,0,hsf#,status2Z) 
bwdimscale(outZ,0,hsf#,status2Z) 
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NAME 


we_min 
PURPOSE 


This function compares a constant with each element of an n-dimensional 
input waveform array and places the minimum values in an n-dimensional 
Output waveform array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTY PE 
we_min(in, const, out) 


WAVEFORM *in, *out; 
double const; 


Where: 
In: 
pointer to the input waveform 


const: 
constant of type double. 


out: 
pointer to the output waveform which will hold the minimums of ele- 
ments of in with const. 


DESCRIPTION 


The least number of dimensions and the least number of elements in any 
given dimension of im or out are used as the basis for determining the ex- 
tent to which out is "filled" with minimums. For example, if in has 4 ele- 
ments along its first dimension and out has 2 elements along its first 
dimension, the first 2 elements along the first dimension of out will be 
"filled" with minimums. 


The following examples should make this clear: 


in out Portion of out holding minimums 
4x4x3 2x2 2x2 

1x4x1 1x1x4 1x1x1 (or 1 element) 

2x2u2 4x4 2x2 

4x4x4 4x4x4 4x4x4 


where 4x4x3 means "4 elements along the first dimension, 4 elements along 
the second dimension, and 3 elements along the third dimension." 
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Each “element” is actually an ordered n-tuple. Function wc_min only uses 

the first tuple of each n-tuple in in to determine the minimum which is 

stored in the first tuple of the corresponding element in out. The first tuple 

of the first element of the first dimension of in is added to the constant and 

the minimum is stored in the first tuple of the first element of the first § 
dimension of out, etc. 


All waveforms must be valid, but the data type of the first tuples of each 
waveform do not need to be the same. we_min performs the comparison in 
double precision and coerces the results into the type of the out waveform 
array. 


wc_min returns an error code as defined in spd.h indicating whether it was 
able to perform correctly or not. 
SEE ALSO 
wav.h 
spd.h 


BASIC FORMAT 


CALL bwemin(inZ, const#, outZ, statusZ) 


Where: 


ino ©} 
integer identifying the input waveform. 


const# 
constant of the type double. 


out% 
integer identifying the output waveform which will hold the minimums 
of elements of in with const. 


status % 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
C 
#include “tekspd.h" 
ERRORTYPE status; 


WAVEFORM *in, *out; 
double num; 


status = we_min(in, num, Gout); ®@ 


status = wf tunits(tup_units(in,0),COPY,0,out); /* copy units */ 
status = wf_dunits(dim_units(in,0),COPY,0,out); 


dim_scale(out,0) = dim_scale(in,0); 
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BASIC: 


’ SINCLUDE: '\tek\spd\include\tekspd.bi’ 
in% = 1: outz = 2 


call bwemin(inZ, num#, out%, status2Z) 


* set units and scaling for waveform outZ 
brtupunits(inZ,0,inVunitsS, inVlenZ,statusZ) 
bwftunits(inVunitsS ,0Z,out2Z, status2) 


brdimunits(inZ,0,inHunitsS, inHlenZ,statusZ) 
bwfdunits(inHunitsS,0Z,outZ, statusZ) 


brdimscale(inz,0,hsf#,status2Z) 
bwdimscale(outZ,0,hsf#,statusZ) 
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NAME 
we mult 


PURPOSE - 


This function multiplies each element of an n-dimensional input waveform 
array by a constant and places the products in an n-dimensional output 
waveform array. 


SYNOPSIS 
#include “tekspd.h" 


ERRORTYPE 
we_mult(in, const, out) 


WAVEFORM *in, *out; 
double const; 


Where: 
In: 

pointer to the input waveform 
const: 


constant of type double. 
out: 


pointer to the output waveform which will hold the products of ele- 
ments of im with const. 


DESCRIPTION 


The least number of dimensions and the least number of elements in any 
given dimension of in or out are used as the basis for determining the ex- 
tent to which out is "filled" with products. For example, if in has 4 elements 
along its first dimension and out has 2 elements along its first dimension, 
the first 2 elements along the first dimension of out will be “filled” with 


products. 
The following examples should make this clear: 
in out Portion of out holding products 
4x4x3 2x2 pa 
1x4x1 lx1x4 1x1x1 (or 1 element) 
2x2x2 4x4 2x2 ®@ 
4x4x4 4x4x4 4x4x4 


where 4x4x3 means "4 elements along the first dimension, 4 elements along 
the second dimension, and 3 elements along the third dimension." 
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Each "element" is actually an ordered n-tuple. Function we_mult only uses 
the first tuple of each n-tuple in in to create the product that is stored in 
the first tuple of the corresponding element in out. For example, the first 
tuple of the first element of the first dimension of in is multiplied by the 
constant and the product is stored in the first tuple of the first element of 
the first dimension of out. 


All waveforms must be valid, but the data type of the first tuples of each 
waveform do not need to be the same. we_mult performs the multiplication 
in double precision and coerces the results into the type of the out 
waveform array. 


wc_mult returns an error code as defined in spd.h indicating whether it was 
able to perform correctly or not. 


SEE ALSO 


wav.h 
spd.h 


BASIC FORMAT 


CALL bwemult(inZ, const#, outZ, statusZ) 


Where: 


ino 
integer identifying the input waveform. 


const# 
constant of the type double. 


out% 
integer identifying the output waveform which will hold the products of 
elements of in with const. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
C: 
#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM *in, *out; 


double num; 


status = we_mult(in, num, &out); 


status = wf_tunits(tup_units(in,0),COPY,0,out); /* copy units */ 
Status = wf_dunits(dim_units(in,0),COPY,0,out); 


dim_scale(out,0) = dim_scale(in,0); 
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BASIC: 


* SINCLUDE: ’\tek\spd\include\tekspd.bi’' 

int = 1: out% = 2 ©} 
call bwemult(inZ, num#, out%Z, statusZ) 

* set units and scaling for waveform outZ 
brtupunits(inZ,0,inVunitsS,inVlenZ, status2Z) 
bwftunits(inVunitsS, 0%, outZ,statusZ) 


brdimunits(inZ,0,inHunitsS, inHlenZ,status2Z) 
bwfdunits(inHunitsS ,02,outZ,status7Z) 


brdimscale(inZ,0,hsf#,statusZ) 
bwdimscale(outZ,0,hsf#, statusZ) 
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NAME 


wc _sub 


PURPOSE 


This function subtracts a constant from each element of an n-dimensional 
input waveform array and places the differences in an n-dimensional out- 
put waveform array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
we_sub(in, const, out) 


WAVEFORM *in, *out; 
double const; 
Where: 
In: 
pointer to the input waveform 


const: 
constant of type double. 


out. 
@ pointer to the output waveform which will hold the differences of ele- 
ments of in with const. 


DESCRIPTION 


The least number of dimensions and the least number of elements in any 
given dimension of in or out are used as the basis for determining the ex- 
tent to which out is "filled" with differences. For example, if in has 4 ele- 
ments along its first dimension and out has 2 elements along its first 
dimension, the first 2 elements along the first dimension of out will be 
"filled" with differences. 


The following examples should make this clear: 


in out Portion of out holding differences 
4x4x3 2x2 2x2 
1x4x1 lx1x4 1x1x1 (or 1 element) 
2x2x2 4x4 2x2 
@ 4x4x4 4x4x4 4x4x4 


where 4x4x3 means "4 elements along the first dimension, 4 elements along 
the second dimension, and 3 elements along the third dimension." 
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Each "element" is actually an ordered n-tuple. Function we_sub only uses 
the first tuple of each n-tuple in in to create the difference that is stored in 
the first tuple of the corresponding element in out. For example, the con- 
stant is subtracted from the first tuple of the first element of the first dimen- 
sion of in and the difference is stored in the first tuple of the first element 
of the first dimension of out. 

All waveforms must be valid, but the data type of the first tuples of each 
waveform do not need to be the same. we_sub performs the subtraction in 
double precision and coerces the results into the type of the out waveform 
array. 

we_mult returns an error code as defined in spd.h indicating whether it was 
able to perform correctly or not. 


SEE ALSO 
wav.h 
spd.h 
BASIC FORMAT 


CALL bwesub(in%, const#, outZ, statusZ) 


Where: 
in% 
integer identifying the input waveform. 


const# 
constant of the type double. 


out% 
integer identifying the output waveform which will hold the differences 
of elements of in with const. 


status % 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 


EXAMPLE 
oe: 
#include "tekspd.h" 
ERRORTYPE status; 
WAVEFORM *in, *out; 
double num; 


status = we_sub(in, num, &out); 


status = wf_tunits(tup_units(in,0),COPY,0,out); /* copy units */ 
Status = wf_dunits(dim_units(in,0),COPY,0,out); 


dim_scale(out,0) = dim_scale(in,0); 
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BASIC: 


*" SINCLUDE: '\tek\spd\include\tekspd.bi’ 
inZ% = 1: outZ = 2 


call bwesub(inZ, num#, outZ, statusZ) 
" set units and scaling for waveform out2Z 
brtupunits(inZ,0,inVunitsS,inVlenZ, status2Z) 


bwftunits(inVunitsS, 02%, outZ, statusZ) 


brdimunits(inz,0,inHunitsS, inHlenZ,status7Z) 
bwfdunits(inHunitsS,02Z,outZ,statusZ) 


brdimscale(inz,0,hsf#,statusz2Z) 
bwdimscale(outZ,0,hsf#,statusZ) 
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NAME 
wf_dlabel 


PURPOSE 


This function assigns a label to a dimension. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
wf_dlabel (label, copy_link, dimmum, wave) 


char *label; 
int copy_link; 
int dimnum; 
WAVEFORM *wave; 


Where: 


label: 
pointer to a NULL terminated character string defining the label. 


copy_link: 
flagword used to indicate if a copy of the string is to be made; defined 
values are COPY or LINK. 

dimnum: 
number of the dimension to assign the label to. 


wave: 
pointer to the waveform to store the label. 


DESCRIPTION 


wf _dlabel assigns the label string as the label for the specified dimension, 
dimnum of the waveform. If a label has already been defined for this dimen- 
sion, it is deleted before assigning the new label to the waveform. 


If the copy link flag is set to COPY, memory space for the label string is al- 
located and the string copied to this area. The d_label element for the 
specified dimension is set to point to the copied string. The WFD_LABEL 
bit in the d_flags field is set to indicate that space has been allocated for 
this string. 

Setting the copy link flag to LINK, causes the d_label element in the 
specified dimension to point to the /abel string. The WFD_LABEL bit is 
reset, indicating that no memory has been allocated for this string. 


Removing a label from a waveform is accomplished by setting /abel to NIL 
and calling this function. The label string is removed in the following 
fashion. If the d_label element is not NIL and the WFD_LABEL bit is set, 
then the string is freed from memory with d_label/ being set to NIL and 
WFD_LABEL being reset. Otherwise, d_label is just set to NIL. 
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The macro, dim_label, can be used to retrieve the pointer to this label 
string from the waveform structure. 


wf _dlabel issues a FATAL error if: 
wave equals NIL. 
wave is not a valid waveform. 
dimnum < 0 or dimnum > = number of dimensions in waveform. 
There is not enough free memory available to copy the label string into. 


wf_dlabel issues a WARNing error if copy link is not COPY or LINK; 
LINK is assumed. 


If a FATAL error occurs, the state of wave is left unchanged. 
This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 
SEE ALSO 
wav.h 
spd.h 


BASIC FORMAT 


CALL bwfdlabel( labelS, dimmumZ, wave%, statusZ ) 


Where: 


label$ 
a character string defining the label. COPY mode is used from 
QuickBASIC. 


dimnum% 
number of the dimension to assign the label to. 


wave Jo 
integer identifying the waveform to store the label. 


status% 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
wf_dunits 


PURPOSE 
This function associates a units string with a dimension. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
wf_dunits (units, copy_link, dimnum, wave) 


char *units; 
int copy_link; 
int dimnum; 
WAVEFORM *wave; 


Where: 


units: 
pointer to a NULL terminated character string defining the units. 
copy_link: 
flagword used to indicate if a copy of the string is to be made; defined 
values are COPY or LINK. 


dimnum: 
number of the dimension to assign the units to. 


wave: 
pointer to the waveform to store the units. 


DESCRIPTION 


wf _dunits assigns the units string as the units label for the specified dimen- 
sion, dimnum, of the waveform. If a units label has already been defined for 
this dimension, it is deleted before assigning the new label to the waveform. 


If the copy_link flag is set to COPY, memory space for the units string is al- 
located and the string copied to this area. The d_units element for the 
specified dimension is set to point to the copied string. The WFD_UNITS 
bit in the d_flags field is set to indicate that space has been allocated for 
this string. 

Setting the copy link flag to LINK, causes the d_units element in the 
specified dimension to point to the units string. The WFD_UNITS bit is 
reset, indicating that no memory has been allocated for this string. 


Removing a units label from a waveform is accomplished by setting units to 
NIL and calling this function. The units string is removed in the following 
fashion. If the d_units element is not NIL and the WFD_UNITS bit is set, 
then the string is freed from memory with d_units being set to NIL and 
WFD_UNITS being reset. Otherwise, d_units is just set to NIL. 
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The macro, dim_units, can be used to retrieve the pointer to this units 
string from the waveform structure. 


wf dunits issues a FATAL error if: 
wave equals NIL. 
wave is not a valid waveform. 
dimnum < 0 or dimnum > = number of dimensions in waveform. 
There is not enough free memory available to copy the units string into. 


wf_dunits issues a WARNing error if copy _link is not COPY or LINK; 
LINK is assumed. 


If a FATAL error occurs, the state of wave is left unchanged. 
This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 
SEE ALSO 
wav.h 
spd.h 
BASIC FORMAT 


CALL bwfdunits( unitsS, dimnumZ, waveZ, statusZ ) 


Where: 


units$ 
a character string defining the units. COPY mode is used from 
QuickBASIC. 


dimnum% 
number of the dimension to assign the units to. 


wave Yo 
integer identifying the waveform to store the units. 


status [% 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
wf_notes 


PURPOSE 
This function assigns a notes string to the notes area of the waveform. 


SYNOPSIS 
#include "tekspd.h” 


ERRORTY PE 
wf notes (notes, copy_link, wave) 


char *notes; 
int copy_link; 
WAVEFORM *wave; 


- Where: 
notes: 


pointer to a NULL terminated character string defining the notes infor- 
mation. 


copy_link: 
flagword used to indicate if a copy of the string is to be made; defined 
values are COPY or LINK. 


wave: 
pointer to the waveform to assign the notes to. 


DESCRIPTION 


wf notes assigns the notes string to the waveform. If wave already contains a 
notes string, it is deleted before assigning the new notes string. 


If the copy link flag is set to COPY, memory space for the notes string is al- 
located and the string copied to this area. The w_notes element in wave is 
set to point to the copied string. The WF_NOTES bit in the w_flags field is 
set to indicate that space has been allocated for this string. 


Setting the copy link flag to LINK, causes the w_notes element in wave to 
point to the notes string. The WF_NOTES bit is reset, indicating that no 
memory has been allocated for this string. 


Removing a notes string from a waveform is accomplished by setting notes 
to NIL and calling this function. The notes string is removed in the follow- 
ing fashion. If the w_notes element is not NIL and the WF_NOTES bit is 
set, then the string is freed from memory with w_notes being set to NIL and 
WF_NOTES being reset. Otherwise, w_notes is just set to NIL. 


The macro, notes _ptr, can be used to retrieve the pointer to this notes string 
from the waveform structure. 
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wf_notes issues a FATAL error if: 
wave equals NIL. 
wave is not a valid waveform. 


There is not enough free memory available to copy the notes string into. 


© wf_notes issues a WARNing error if copy link is not COPY or LINK; LINK 
is assumed. 


If a FATAL error occurs, the state of wave is left unchanged. 
This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 

SEE ALSO 


wav.h 
spd.h 


BASIC FORMAT 


CALL bwfnotes( notesS, waveZ, statusZ ) 


Where: 


notes$ 
a character string defining the notes information. COPY mode is used 


¢ from QuickBASIC. 
wave % 


integer identifying the waveform to assign the notes to. 


status Zo 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
wf title 


PURPOSE 
This function assigns a title to a waveform. 


SYNOPSIS 
#include "tekspd.h”" 


ERRORTYPE 
wf_title (title, copy_link, wave) 


char *title; 
int copy_link; 
WAVEFORM *wave; 


Where: 


ttle: 
pointer to a NULL terminated character string defining the title. 
copy_link: 
flagword used to indicate if a copy of the string is to be made; defined 
values are COPY or LINK. 


wave: 
pointer to the waveform to be titled. 


DESCRIPTION 


wf_utle assigns the title string as the title of the waveform. If wave already 
contains a title, it is deleted before assigning the new title to the waveform. 


If the copy link flag is set to COPY, memory space for the title string is allo- 
cated and the string copied to this area. The w_title element in wave is set 

to point to the copied string. The WF_TITLE bit in the w_flags field is set 

to indicate that space has been allocated for this string. 


Setting the copy link flag to LINK, causes the w_title element in wave to 
point to the uitle string. The WF_TITLE bit is reset, indicating that no 
memory has been allocated for this string. 


Removing a title from a waveform is accomplished by setting title to NIL 
and calling this function. The title string is removed in the following 
fashion. If the w_title element is not NIL and the WF_TITLE bit is set, 
then the string is freed from memory with w_title being set to NIL and 
WF_TITLE being reset. Otherwise, w_title is just set to NIL. 


The macro, title_ptr, can be used to retrieve the pointer to this title string 
from the waveform structure. 
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wf_title issues a FATAL error if: 
wave equals NIL. 
wave is not a valid waveform. 
There is not enough free memory available to copy the title string into. 


wf_title issues a WARNing error if copy _link is not COPY or LINK; LINK 
is assumed. 


If a FATAL error occurs, the state of wave is left unchanged. 
This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 
SEE ALSO 
wav.h 
spd.h 
BASIC FORMAT 


CALL bwftitle( titleS, waveZ, statusZ ) 


Where: 


title$ 
a character string defining the title. COPY mode is used from 
QuickBASIC. 

wave % 
integer identifying the waveform to be titled. 

status Yo 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
wf _tlabel 


PURPOSE 6 
This function assigns a label to a tuple. 


SYNOPSIS 
#include "“tekspd.h" 


ERRORTYPE 
wf tlabel (label, copy_link, tupnum, wave) 


char *label; 
int copy_link; 
int tupnum; 
WAVEFORM *wave; 


Where: 


label: 
pointer to a NULL terminated character string defining the label. 


copy link: 
flagword used to indicate if a copy of the string is to be es defined 


values are COPY or LINK. ©} 
tupnum: 


number of the tuple to assign the label to. 


wave: 
pointer to the waveform to store the label. 


DESCRIPTION 


wf_tlabel assigns the label string as the label for the specified tuple, tupnum, 
of the waveform. If a label has already been defined for this tuple, it is 
deleted before assigning the new label to the waveform. 


If the copy link flag is set to COPY, memory space for the label string is al- 
located and the string copied to this area. The t abel element for the 
specified tuple is set to point to the copied string. The WFT LABEL bit in 
the t flags field is set to indicate that space has been allocated for this string. 


Setting the copy link flag to LINK, causes the t label element in the 


specified tuple to point to the /abe/ string. The WFT_LABEL bit is reset, in- 
dicating that no memory has been allocated for this string. 


Removing a label from a waveform is accomplished by setting /abel to NIL @ 
and calling this function. The label string is removed in the following 

fashion. If the ¢ label element is not NIL and the WFT_LABEL bit is set, 

then the string is freed from memory with t label being s set to NIL and 

WFT_LABEL being reset. Otherwise, t label i is just set to NIL. 
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The macro, tup label, can be used to retrieve the pointer to this label string 
from the waveform structure. 


wf tlabel issues a FATAL error if: 
wave equals NIL. 
wave is not a valid waveform. 
tupnum < 0 or tupnum > = number of tuples in waveform. 
There is not enough free memory available to copy the label string into. 


wf_tlabel issues a WARNing error if copy _link is not COPY or LINK; 
LINK is assumed. 


If a FATAL error occurs, the state of wave is left unchanged. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 


SEE ALSO 


wav.h 
spd.h 


BASIC FORMAT 


CALL bwtlabel( labelS, tupnum%, wave%, statusZ ) 


Where: 


label$ 
a character string defining the label. COPY mode is used from 
QuickBASIC. 

tupnum Yo 
number of the tuple to assign the label to. 


Cc 


wave %o 
integer identifying the waveform to store the label. 


status Yo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
wf_to_afile 


PURPOSE ® 
Writes a waveform to a file in ASCII ADIF format. 
SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 
wf _to_afile(inwave, outfile) 


WAVEFORM *inwave; 
char *outfile; 


Where: 


inwave: 
pointer to the source waveform. 


outfile: 
pointer to the name of the file in which to store the waveform data. 
DESCRIPTION 


wf to_afile stores the waveform pointed to by inwave in the file name © 
specified by outfile. The data is written out in ASCII ADIF form (i.e., it is 
“human readable" and may be edited using most editors). 


The format of the file (ADIF) is specified in Appendix E. 


The source waveform must be valid. The waveform is stored as an original 
and any link to a previous waveform is lost. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 

SEE ALSO 
Include files: 


wav.h 
spd.h 


Signal processing functions: 


afile to_wf 
file to _wf 


wf to file 
APPENDIX E 
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BASIC FORMAT 


CALL bwftoafile( inmwaveZ, outfileS, statusZ ) 


© Where: 
inwave Zo 
integer identifying the source waveform. 
outfiles 


string identifying the name of the file in which to store the waveform 
data. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
wf_to_arr 


PURPOSE 


This function creates an array and fills it with the data from the source 
waveform array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
wf_to_arr (inwave, arrayptr) 


WAVEFORM *inwave; 
BYTE **arrayptr; 


Where: 
inwave: 
pointer to the source waveform. 


arrayptr. 
address of the pointer to the array to be created and filled. 


DESCRIPTION 


wf to_arr allocates memory space for the output array. It then copies the 
data from the source waveform array to the output array. It returns the ad- 
dress of the output array in arrayptr. 


The output array is contiguous. If the source waveform array has more than 
one dimension, the array is written such that the elements from the last 
dimension are adjacent and the elements from the first dimension are the 
farthest apart. More precisely, the distance between elements (in bytes) for 


the last dimension is the data element size. Then working backwards, the 
distance between elements for each dimension, 7, is the distance for dimen- 


sion n+1 times the length of dimension n+1. As an example, the offset (in 
bytes) from the array pointer for element{[x, y, z] of a three dimensional 
array 1S: 


x * distance for the first dimension + 
y * distance for the second dimension + 
z * distance for the last dimension. 


The memory allocated for the output array can be freed by calling fr_array. 
wf _to_arr issues a FATAL error if: 
inwave is not a valid waveform. 


There is not enough free memory available for the output array and the 
temporary waveform structures. 


If a FATAL error occurs, *arrayptr is set to NIL. 
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This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 


SEE ALSO 


spd.h 
wav.h 
fr_array 


BASIC FORMAT 


CALL bwftoarr( inwaveZ, arrayptrS, statusZ ) 


Where: 


inwave% 
integer identifying the source waveform. 

arrayptr# (0) 
first element of the array to be created and filled. The data type of the 
array must correspond to the data type of the waveform. 


status [ 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
wf_to_file 


PURPOSE © 


Write a waveform to a file in binary ADIF format. 


SYNOPSIS 
#include “tekspd.h" 


ERRORTYPE 
wf to file(inwave, outfile) 


WAVEFORM *inwave; 
char *outfile; 


Where: 


inwave: 
pointer to the source waveform. 


outfile: 
pointer to the name of the file in which to store the waveform data. 


DESCRIPTION 
wf to_file stores the waveform pointed to by inwave in the file name © 
specified by outfile. The numeric data is written out in binary form (i.e., it is 
not "human readable"). For most waveforms this is the fastest and most effi- 
cient way of storing data. 


A standard file header is written at the beginning of the file to indicate an 
ADIF waveform file. This is followed by the waveform description infor- 
mation taken from the waveform data structure. The waveform array data 
is then written out element by element to complete the operation. 


The source waveform must be valid. The waveform is stored as an original 
and any link to a previous waveform is lost. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 

SEE ALSO 
Include files: 


wav.h 


spd.h | 
Signal processing functions: 


afile to wf 
file to_wf 
wi to afile 
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BASIC FORMAT 


CALL bwftofile( inZ, outS, status2Z ) 


} Where: 
inZo 


integer identifying the source waveform. 


outs 
name of the file in which to store the waveform data. 


status Zo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
wf_tunits 


PURPOSE 
This function associates a units string with a tuple. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
wf_tunits (units, copy_link, tupnum, wave) 


char *units; 
int copy_link; 
int tupnum; 
WAVEFORM *wave; 


Where: 
units: 

pointer to a NULL terminated character string defining the units. 
copy_link: 


flagword used to indicate if a copy of the string is to be made; defined 
values are COPY or LINK. 


tupnum: 
number of the tuple to assign the units to. 


wave: 
pointer to the waveform to store the units. 


DESCRIPTION 


wf tunits assigns the units string as the units label for the specified tuple, 
tupnum of the waveform. If a units label has already been defined for this 
tuple, it is deleted before assigning the new units to the waveform. 


If the copy link flag is set to COPY, memory space for the units string is al- 
located and the string copied to this area. The ¢_units element for the 
specified tuple is set to point to the copied string. The WFT_UNITS bit in 
the ¢ flags field is set to indicate that space has been allocated for this string. 


Setting the copy _link flag to LINK, causes the t_units element in the 
specified tuple to point to the units string. The WFT_UNITS bit is reset, in- 
dicating that no memory has been allocated for this string. 

Removing a units label from a waveform is accomplished by setting units to 
NIL and calling this function. The units string is removed in the following 
fashion. If the t units element is not NIL and the WFT_UNITS bit is set, 
then the string is freed from memory with t_units being s set to NIL and 
WFT_UNITS being reset. Otherwise, t_units is just set to NIL. 
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The macro, tup_units, can be used to retrieve the pointer to this units string 
from the waveform structure. 


wf_tunits issues a FATAL error if: 
wave equals NIL. 
wave is not a valid waveform. 
tupnum < 0 or tupnum > = number of tuples in waveform. 
There is not enough free memory available to copy the units string into. 


wf_tunits issues a WARNing error if copy link is not COPY or LINK; 
LINK is assumed. 


If a FATAL error occurs, the state of wave is left unchanged. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 


SEE ALSO 


wav.h 
spd.h 


BASIC FORMAT 


CALL bwftunits( unitsS, tupnumZ, waveZ, statusZ ) 


Where: 


units$ 
a character string defining the units. COPY mode is used from 
QuickBASIC. 


tupnum % 
number of the tuple to assign the units to. 


wave Yo 
integer identifying the waveform to store the units. 


status% 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 


write_num 


PURPOSE ® 


Puts a number into a waveform element. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
write num (num, tuple, index, wave) 


double num 

int tuple; 

long index[]; 
WAVEFORM *wave; 
Where: 


Aum: 
source variable 


tuple: 
tuple to be written (numbered from zero) 


index © 
pointer to an array of indices (coordinates) which specify the location of 
the datum to be written. (numbered from zero) 


wave: 
pointer to the target waveform 
DESCRIPTION 


write_num writes the number into the waveform based on the information 
in index. num is written into the location given by index. If tuple is not a 
valid tuple number for wave, or if any of the elements of index is not a valid 


index for wave, a FATAL error will be issued. 


It is assumed that wave is a valid waveform. The number of elements in 
index must be the same as the number of dimensions in wave. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it executed correctly. 


SEE ALSO 


wav.h 
spd.h 
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BASIC FORMAT 


CALL bwritenum( num, tupleZ, index&(0), wavez, statusZ ) 


Where: 


num# 
source variable. 


tuple% 
tuple to be written (numbered from zero). 

index&(0) 
first element of array of indices (coordinates) which specify the location 
of the datum to be written (numbered from zero). 


wave Yo 
integer identifying the target waveform. 


status Zo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 


zone_dim 


PURPOSE 
Zones (changes the length of) one dimension of the waveform array. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTY PE 
zone_dim (wave, dim, begin, end, del_keep, subwave) 


WAVEFORM *wave; 
int dim, del_ keep; 
long begin, end; 
WAVEFORM **subwave; 


Where: 


wave: 
pointer to the source waveform. 

dim: 
dimension number of the dimension to be zoned. (Dimensions are num- 
bered from zero.) 

begin: 
index of new first element in zoned dimension. (Indexes are numbered 
from zero.) 


end: 
index of new last element in zoned dimension. 

del keep: 
flagword used to indicate whether the source waveform should be 
deleted if possible; defined values are KEEP or DELETE. 


subwave: 
address of the pointer to the subordinate waveform to be created. 


DESCRIPTION 


zone_dim allocates memory space for a subordinate waveform structure 
and its associated substructures. It returns the address of the new subor- 
dinated waveform in subwave. 


This function creates a subordinate waveform that accesses a subset of the 
source waveform’s array. It allows the beginning and ending elements of 
one of the dimensions to be redefined, shortening the length of that dimen- 
sion. However, the number of dimensions is unchanged and the data ele- 
ment is unaltered. The new waveform is similar to the source except that 
the array size is adjusted to reflect the new length of the zoned dimension. 
More than one dimension can be zoned by successive calls to zone_dim. 
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zone_dim does not delete any array data, but the data elements in the 
zoned dimension that are outside the zone are not accessible from the new 
subordinate waveform. However, by using copy _wf() on the resultant 
waveform, a new waveform with compacted array data can be created. 


zone_dim may also attempt to delete the source waveform, wave, depending 
on the value of del_keep and whether wave is an original waveform or not. 
If del_keep is DELETE and wave is not an original waveform, subwave is 
made subordinate to the previous waveform of wave, the subordinate 
counter of the previous waveform of wave is incremented, and an attempt is 
made to delete wave. If not, subwave is made a subordinate of wave and the 
subordinate counter of wave is incremented. 


String fields (titles, notes, dimension labels, dimension units, tuple labels 
and tuple units) for subwave are LINKed to the string information in wave. 
That is, the pointer to the string in wave is copied to subwave, but the cor- 
responding bit in the bit flags field is reset indicating that no memory was 
allocated for subwave to contain the string. When space has been allocated 
for a string in wave and wave is to be DELETEgd, the appropriate bit flag is 
set in subwave so that the strings will be properly maintained. 


The information in the new WAVEFORM structure is copied from the 
source except: 


The pointer to the previous waveform is set to either wave or the pre- 
vious waveform of wave as explained above. 
The number of subordinate waveforms is set to zero. 


The bit flags are set to show that the structure space was allocated by 
one of the waveform utilities and can, therefore, be released by them. 


The setting of the bit flags for string fields (title and notes) are 
described above. 

The array size is adjusted to reflect the shorter length of the zoned 
dimension. 

The array pointer is adjusted to reflect a possible new origin. 


The pointer to the substructures containing dimension information 
points to the W_DIM structure for the first dimension of the new 
waveform. 


The pointer to the substructures containing the tuple information 
points to the W_TUPLE structure for the first tuple of the new 
waveform. 


The information in the W_DIM structures of the new waveform is copied 
from the source except: 


The dimension length of the zoned dimension is set to end - begin + 1. 


The axis offset of the zoned dimension is adjusted to reflect the new 
beginning element of the dimension. 


Signal Processing & Display 8-281] 


Signal Processing 


zone_dim 


The information in the W_TUPLE structures of the new waveform is 
copied from the source except: 


The string field bit flags for tuple labels and units are set as described 
above. 


zone_dim issues a FATAL error if: 
wave 1S not a valid waveform. 
dim < 0 or dim > = number of dimensions in wave. 


begin < 0 or begin > end or end >= the length of the dimension to be 
zoned. 


There is not enough free memory available for the new waveform struc- 
tures. 


zone_dim issues a WARNing error if: 
del_keep is not KEEP or DELETE; KEEP is assumed. 


wave is a Subordinate waveform and del_keep is DELETE, but wave 
cannot be deleted (i.e., the bit flags do not indicate that the structure 
space was allocated by one of the waveform utilities or the subordinate 
waveform counter is not zero). 


If a FATAL error occurs, *subwave is set to NIL. 
SEE ALSO 


wav.h 
spd.h 


NOTES 


If subwave points to the address of wave upon function entry, it is then the 
user’s responsibility to note the waveform structure previously associated 
with wave. 


BASIC FORMAT 


CALL bzonedim( waveZ, dimZ, begin&, end&, delkeepZ, sub- 
wavez,statusZ ) 


Where: 


wave Jo 
integer identifying the source waveform. 


dim% 
dimension number of the dimension to be zoned. (Dimensions are 
numbered from zero.) 

begin& 
index of new first element in zoned dimension. (Indexes are numbered 
from zero.) 


8-282 Signal Processing & Display 


Signal Processing 


zone_dim 
end& 
index of new last element in zoned dimension. 
delkeep[% 
flagword used to indicate whether the source waveform should be 
@ deleted if possible. Use pre-defined constant KEEP% or DELETE%. 
subwave% 


integer identifying the subordinate waveform to be created. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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Section 9 


Acquisition 


Listed on the following pages in alphabetical order, are detailed descriptions of 
the Waveform Acquisition functions, found in the ACQMS.LIB library. These 
functions duplicate the functionality of the SPDMENU acquisition forms. All 
instruments supported by SPDMENU are supported by the acquisition library, 
with the exception of the RS-232 interface to the Tektronix 2230. 


The philosophy behind the SPD acquisition functions is to provide access to as 
many of the waveform acquisition modes and data sources of the target instru- 
ment as possible. In addition, automatic searching for instrument addresses on 
the GPIB bus is provided. If this feature is used, only the first instrument of the 
targeted type is found. Alternatively, users may specify the address as a 
parameter. For many instruments, a "normalize" parameter is specified. If this 
is set to TRUE, then the scale and offset factors are applied to the data array of 
the acquired waveform and the units specified by the instrument are attached to 
the waveform. If, however, FALSE is specified, the vertical offset and scale fac- 
tor are stored in the waveform, but are NOT applied to the data array. In this 
case, the vertical units are set to "Dig Levels". 


The description of each function in this section is formatted as follows: 


Name: name of function 

Purpose: tells what the function does 

Synopsis: shows the calling format for the function as 
follows: 


function name (arguments) 
type declarations 


Description: full description of the function 


BASIC Format: describes the BASIC calling format and dif- 
ferences between type declarations. 
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NAME 


getl1k 


PURPOSE 


Acquire a waveform from a Tektronix 11000 series digitizing oscilloscope 
and convert it to the SPD waveform format. 


SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 
getllK(wave,wtype,source,wavenum, address, timeout normalize) 
WAVEFORM **wave; 

short wtype; 

short source; 

short wavenum; 

short address; 

short timeout; 

short normalize; 


Where: 


wave: 
address of pointer to the newly acquired waveform. 

wtype: 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are W_ FLOAT and W_DOUBLE. 


source: 
the data source from which the waveform is to be acquired. Valid pre- 
defined constants are TRACE and STO. 


wavenum: 
the trace or storage location to acquire. If source is TRACE, then 
wavenum must be a number between 1 and 8. If source is STO, then 
wavenum must be a number between 1 and 256. 


address: 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment or else an integer between 0 and 29. 


timeout: 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE, 
T10us, T30us, T100us, T300us, Tims, T3ms, T10ms, T30ms, T100ms, 
T300ms, T1s, T3s, T10s, T30s, T100s, T300s, or T1000s where: 
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us = microseconds 
ms = milliseconds 
S = seconds. 
© normalize: . 
an integer that specifies whether or not the vertical scale and offset 


should be applied to the data array of the waveform, and whether the 
vertical units from the preamble should be attached to the waveform. 
Use the pre-defined constant TRUE to apply the scale and offset and 
to attach the vertical units from the preamble. Use FALSE to store the 
scale and offset without applying them to the data. FALSE also causes 
the string ‘Dig Levels’ to be used for the vertical units. 


DESCRIPTION 


get11K acquires a waveform from the specified data source of a Tektronix 
11000 series digitizing oscilloscope. The function obtains preamble and 
wave data from the instrument at the address specified by address, formats 
the data into an SPD waveform, and puts a pointer to the new waveform in 
*wave. get11K allocates the memory for the acquired waveform. Because of 
this, *wave should not point to allocated memory before calling get11K, 
otherwise the memory pointed to will be lost to the program. If this func- 
tion is used in a loop to acquire many waveforms, be sure to use free_wf to 
free previously used memory. 


get11K issues a FATAL under the following conditions: 
Source is not equal to TRACE, or STO. 


Wavenum is not between 1 and 8 (for TRACE mode) or between 1 and 
256 (for STO mode). 


Wtype is not equal to W_ FLOAT or W_DOUBLE. 

Address is not equal to POLL or a value between 0 and 29. 
Timeout is not equal to one of the values listed above. 

A GPIB error occurs in acquiring data from the instrument. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 


acq.h 
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BASIC FORMAT 


Call bget11K(waveZ ,wtype% , source% ,wavenumi2, ad- 
dress%Z, timeout%, statusZ) 


Where: 


wave Jo 
integer identifying the newly created waveform 


wtype To 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are WFLOAT% and WDOOUBLE%. 


source Yo 
the data source from which the waveform is to be acquired. Valid pre- 
defined constants are TRACE% and STO%. 


wavenum Yo 
the trace or storage location to acquire. If source% is TRACE%, then 
wavenum% must be a number between 1 and 8. If source% is STO%, 
then wavenum% must be a number between 1 and 256. 


address % 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeout% 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE%, 
T10US%, T30US%, T100US%, T300US%, TIMS%, T3MS%, 
T10MS%, T30MS%, T100MS%, T300MS%, T1S%, T3S%, T10S%, 
T30S%, T100S%, T300S%, or T1000S% where: 


US = microseconds 
MS = milliseconds 
S = seconds. 


normalize%: 
an integer that specifies whether or not the vertical scale and offset 
should be applied to the data array of the waveform. Use the pre- 
defined constant TRUE% to apply the scale and offset. Use FALSE% 
to store the scale and offset without applying them to the data. 


status Yo 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
get2220 


© nice 


Acquire a waveform from a Tektronix 2220 or 2221 and convert it to the 
SPD waveform format. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE get2220(wave,wtype, source, address, timeout) 
WAVEFORM **wave; 

short wtype; 

short source; 

short address; 

short timeout; 


Where: 


wave: 
address of pointer to the newly acquired waveform. 


wtype: 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are W FLOAT and W_ DOUBLE. 


source: 
the instrument data source from which the waveform is to be acquired. 
Valid pre-defined constants are CH1, CH2 and REF4. 


address: 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeout: 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE, 
T10us, T30us, T100us, T300us, Tims, T3ms, T10ms, T30ms, T100ms, 
T300ms, T1s, T3s, T10s, T30s, T100s, T300s, or T1000s where: 


us = microseconds 
ms = miliseconds 


S = seconds. 
@ DESCRIPTION 


get2220 acquires a waveform from the specified data source of a Tektronix 
2220 or 2221. The function obtains preamble and wave data from the in- 

strument at the address specified by address, formats the data into an SPD 
waveform, and puts a pointer to the new waveform in *wave. get2220 allo- 
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cates the memory for the acquired waveform. Because of this, *wave should 

not point to allocated memory before calling get2220, otherwise the 

memory pointed to will be lost to the program. If this function is used in a 

loop to acquire many waveforms, be sure to use free_wf to free previously 

used memory. ’ @ 
The Tektronix 2220 and 2221 do not provide scaling information for 

waveforms, so waveforms acquired with this function have "Dig Levels" as 

the vertical units. 


get2220 issues a FATAL under the following conditions: 
Source is not equal to CH1, CH2 or REF4. 
Wrype is not equal to W_ FLOAT or W_ DOUBLE. 
Address is not equal to POLL or a value between 0 and 29. 
Timeout is not equal to one of the values listed above. 
A GPIB error occurs in acquiring data from the instrument. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 


acq.h © 


BASIC FORMAT 


Call bget2220(wave% ,wtype% , sourcez, address% , timeout%, statusZ ) 


Where: 


wave Jo 
integer identifying the newly created waveform 


wtype To 


the data type to use for the data array of the acquired waveform. Valid 


pre-defined constants are WFLOAT% and WDOUBLE%. 


source Yo 
the instrument data source from which the waveform is to be acquired. 
Valid pre-defined constants are CH1%, CH2%, and REF4%. 


address% 
GPIB bus address at which to find the instrument. Value must be 
either POLL% to specify an automatic search on the bus for the instru- 
ment or else an integer between 0 and 29. 6 


timeout% 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE%, 
T10US%, T30US%, T100US%, T300US%, T1MS%, T3MS%, 
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T10MS%, T30MS%, T100MS%, T300MS%, T1S%, T3S%, T10S%, 
T30S%, T100S%, T300S%, or T1000S% where: 


US = microseconds 
MS = milliseconds 
S = seconds. 


status% 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
get2230 


PURPOSE ® 
Acquire a waveform from a Tektronix 2230 and convert it to the SPD 
waveform format. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
get2230(wave,wtype, source, address, timeout ,normalize) 
WAVEFORM **wave; 

short wtype; 

short source; 

short address; 

short timeout; 

short normalize; 


Where: 


wave: 
address of pointer to the newly acquired waveform. 


wtype: 
the data type to use for the data array of the acquired waveform. Valid © 
pre-defined constants are W FLOAT and W_ DOUBLE. 


source: 
the Tek 2230 data source from which the waveform is to be acquired. 
Valid pre-defined constants are CH1, CH2, REF1, REF2, REF3, and 
REF4. 


address: 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeout: 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE, 
T10us, T30us, T100us, T300us, Tims, T3ms, T10ms, T30ms, T100ms, 
T300ms, T1s, T3s, T10s, T30s, T100s, T300s, or T1000s where: 


us = microseconds 
ms = milliseconds 
= seconds. 


normalize: 
an integer that specifies whether or not the vertical scale and offset 
should be applied to the data array of the waveform and whether the 
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vertical units from the preamble should be attached to the waveform. 

Use the pre-defined constant TRUE to apply the scale and offset and 

to attach the vertical units from the preamble. Use FALSE to store the 

scale and offset without applying them to the data. FALSE also causes 
© the string ‘Dig Levels’ to be used for the vertical units. 


DESCRIPTION 


get2230 acquires a waveform from the specified data source of a Tektronix 
2230. The function obtains preamble and wave data from the instrument at 
the address specified by address, formats the data into an SPD waveform, 
and puts a pointer to the new waveform in *wave. get2230 allocates the 
memory for the acquired waveform. Because of this, *wave should not 

point to allocated memory before calling get2230, otherwise the memory 
pointed to will be lost to the program. If this function is used in a loop to ac- 
quire many waveforms, be sure to use free_wf to free previously used 
memory. 


get2230 issues a FATAL under the following conditions: 
Source is not equal to CH1, CH2, REF1, REF2, REF3, or REF4. 
Wtype is not equal to W_ FLOAT or W_DOUBLE. 
Address is not equal to POLL or a value between 0 and 29. 
© Timeout is not equal to one of the values listed above. 
A GPIB error occurs in acquiring data from the instrument. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 


acq.h 
BASIC FORMAT 
Call bget2230(waveZ ,wtypeZ,sourceZ, address%Z, timeout%, statusZ ) 


Where: 


wave Yo 
integer identifying the newly created waveform 


wtype % 
the data type to use for the data array of the acquired waveform. Valid 
@ pre-defined constants are WFLOAT% and WDOUBLE%. 
source Yo 
the Tektronix 2230 data source from which the waveform is to be ac- 
quired. Valid pre-defined constants are CH1%, CH2%, REF1%, 
REF2%, REF3%, and REF4%. 
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address% 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeout % 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE%, 
T10US%, T30US%, T100US%, T300US%, T1MS%, T3MS%, 
T10MS%, T30MS%, T100MS%, T300MS%, T1S%, T3S%, T10S%, 
T30S%, T100S%, T300S%, or T1000S% where: 


US = microseconds 
MS = milliseconds 
S = seconds. 


normalize%: 
an integer that specifies whether or not the vertical scale and offset 
should be applied to the data array of the waveform. Use the pre- 
defined constant TRUE% to apply the scale and offset. Use FALSE% 
to store the scale and offset without applying them to the data. 


statusT%o 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
get2430 


PURPOSE 


Acquire a waveform from a Tektronix 2430, 2430A, 2432, or 2440 and con- 
vert it to the SPD waveform format. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
get2430(wave,wtype, source, address, timeout ,normalize) 
WAVEFORM **wave; 

short wtype; 

short source; 

short address; 

short timeout; 

short normalize; 


Where: 


wave: 
address of pointer to the newly acquired waveform. 


wtype: 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are W_ FLOAT and W_ DOUBLE. 


source: 
the instrument data source from which the waveform is to be acquired. 
Valid pre-defined constants are CH1, CH2, REF1, REF2, REF3, 
REF4, ADD, MULT, CH1D, CH2D, ADDD, and MULTD. 


address: 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeout: 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE, 
T10us, T30us, T100us, T300us, Tims, T3ms, T10ms, T30ms, T100ms, 
T300ms, T1s, T3s, T10s, T30s, T100s, T300s, or T1000s where: 


us = microseconds 
ms = milliseconds 
S = seconds. 


normalize: 
An integer that specifies whether or not the vertical scale and offset 
should be applied to the data array of the waveform and whether the 
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vertical units from the preamble should be attached to the waveform. 

Use the pre-defined constant TRUE to apply the scale and offset and 

to attach the vertical units from the preamble. Use FALSE to store the 

scale and offset without applying them to the data. FALSE also causes 

the string “Dig Levels’ to be used for the vertical units. © 


DESCRIPTION 


get2240 acquires a waveform from the specified data source of a Tektronix 
2430, 2430A, 2432, or 2440. The function obtains preamble and wave data 
from the instrument at the address specified by address, formats the data 
into an SPD waveform, and puts a pointer to the new waveform in *wave. 
get2430 allocates the memory for the acquired waveform. Because of this, 
*wave should not point to allocated memory before calling get2430, other- 
wise the memory pointed to will be lost to the program. If this function is 
used in a loop to acquire many waveforms, be sure to use free_wf to free 
previously used memory. 


get2430 issues a FATAL under the following conditions: 


Source is not equal to CH1, CH2, REF1, REF2, REF3, REF4, ADD, 
MULT, CH1D, CH2D, ADDD, or MULTD. 


Wtype is not equal to W_ FLOAT or W_DOUBLE. 

Address is not equal to POLL or a value between 0 and 29. 

Timeout is not equal to one of the values listed above. © 
A GPIB error occurs in acquiring data from the instrument. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 
acq.h 
BASIC FORMAT 


Call bget2430(waveZ ,wtype% , source%Z, address%Z, timeout% , statusZ) 


Where: 


wave Yo 
integer identifying the newly created waveform 

wtype% 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are WFLOAT% and WDOUBLE%. 

source % 
the instrument data source from which the waveform is to be acquired. 
Valid pre-defined constants are CH1%, CH2%, REF1%, REF2%, 
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REF3%, REF4%, ADD%, MULT%, CHiD%, CH2D%, ADDD%, 
and MULTD%. 


address% 
©} GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeout% 
An integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE%, 
T10US%, T30US%, T100US%, T300US%, TIMS%, T3MS%, 
T10MS%, T30MS%, T100MS%, T300MS%, T1S%, T3S%, T10S%, 
T30S%, T100S%, T300S%, or T1000S% where: 


US = microseconds 
MS = milliseconds 
S = seconds. 


normalize%: 
an integer that specifies whether or not the vertical scale and offset 
should be applied to the data array of the waveform. Use the pre- 
defined constant TRUE% to apply the scale and offset. Use FALSE% 
® to store the scale and offset without applying them to the data. 


status% 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
get5223 


PURPOSE 


Acquire a waveform from a Tektronix 5223 and convert it to the SPD 
waveform format. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTY PE 

get5223 (wave,wtype, source, address, timeout) 
WAVEFORM **wave; 

short wtype; 

short source; 

short address; 

short timeout; 


Where: 

wave: 
address of pointer to the newly acquired waveform. 

wtype: 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are W FLOAT and W_DOUBLE. 


SOUTTE, 
the Tek 5223 data source from which the waveform is to be acquired. 
Valid pre-defined constants are L, L1, L2, R, R1, or R2. 


address: 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment or else an integer between 0 and 29. 


tuneout: 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE, 
T10us, T30us, T100us, T300us, Tims, T3ms, T10ms, T30ms, T100ms, 
T300ms, T1s, T3s, T10s, T30s, T100s, T300s, or T1000s where: 


us = microseconds 
ms = milliseconds 
Ss = seconds. 


DESCRIPTION 


get5223 acquires a waveform from the specified data source of a Tektronix 
5223. The function obtains preamble and wave data from the instrument at 
the address specified by address, formats the data into an SPD waveform, 
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and puts a pointer to the new waveform in *wave. get5223 allocates the 

memory for the acquired waveform. Because of this, *wave should not 

point to allocated memory before calling get5223, otherwise the memory 
© pointed to will be lost to the program. If this function is used in a loop to ac- 

quire many waveforms, be sure to use free_wf to free previously used 

memory. 


get5223 issues a FATAL under the following conditions: 
Source is not equal to L, L1, L2, R, R1, or R2. 
Wtype is not equal to W FLOAT or W_ DOUBLE. 
Address is not equal to POLL or a value between 0 and 29. 
Timeout is not equal to one of the values listed above. 
A GPIB error occurs in acquiring data from the instrument. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 


acq.h 


© BASIC FORMAT 
“Call bget5223(wave% ,wtype%Z, source%, addressZ, timeout%, statusZ) 


Where: 


wave Jo 
integer identifying the newly created waveform 


wtype Yo 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are WFLOAT% and WDOUBLE%. 


source Yo 
the Tek 5223 data source from which the waveform is to be acquired. 
Valid pre-defined constants are L, L1, L2, R, R1, or R2. 


address % 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeout% 
@ an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE%, 
T10US%, T30US%, T100US%, T300US%, TIMS%, T3MS%, 
T10MS%, T30MS%, T100MS%, T300MS%, T1S%, T3S%, T10S%, 
T30S%, T100S%, T300S%, or T1000S% where: 
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US = microseconds 
MS = milliseconds 


S = seconds. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
get7854 


PURPOSE 


Acquire a waveform from a Tektronix 7854 and convert it to the SPD 
waveform format. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 

get7854 (wave, ,wtype, address, timeout ,normalize) 
WAVEFORM **wave; 

short wtype; 

short address; 

short timeout; 

short normalize; 


Where: 


wave: 
address of pointer to the newly acquired waveform. 


wtype: 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are W FLOAT and W_ DOUBLE. 


address: 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeout: 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE, 


T10us, T30us, T100us, T300us, Tims, T3ms, T10ms, T30ms, T100ms, 
T300ms, T1s, T3s, T10s, T30s, T100s, T300s, or T1000s where: 


us = microseconds 
ms = milliseconds 
Ss = seconds. 


normalize: 
an integer that specifies whether or not the vertical scale and offset 
should be applied to the data array of the waveform, and whether the 
vertical units from the preamble should be attached to the waveform. 
Use the pre-defined constant TRUE to apply the scale and offset and 
to attach the vertical units from the preamble. Use FALSE to store the 
scale and offset without applying them to the data. FALSE also causes 
the string ‘Dig Levels’ to be used for the vertical units. 
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DESCRIPTION 


get7854 acquires a waveform from a Tektronix 7854. The function obtains 

preamble and wave data from the instrument at the address specified by ad- 

dress, formats the data into an SPD waveform, and puts a pointer to the © 
new waveform in *wave. get7854 allocates the memory for the acquired 

waveform. Because of this, *wave should not point to allocated memory 

before calling get7854, otherwise the memory pointed to will be lost to the 

program. If this function is used in a loop to acquire many waveforms, be 

sure to use free_wf to free previously used memory. 


get7854 issues a FATAL under the following conditions: 
Wtype is not equal to W_ FLOAT or W_DOUBLE. 
Address is not equal to POLL or a value between 0 and 29. 
Timeout is not equal to one of the values listed above. 
A GPIB error occurs in acquiring data from the instrument. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 
Include files: 


acq.h o@ 


BASIC FORMAT 


Call bget7854 (wave%Z ,wtype%, address%Z, timeout%, statusZ ) = 


Where: 


wave % 
integer identifying the newly created waveform 

wtype Yo 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are WFLOAT% and WDOUBLE%. 


address% 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeoutYo 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning © 
a timeout error. Valid values are defined by the constants TNONE%, 
T10US%, T30US%, T100US%, T300US%, T1MS%, T3MS%, 
T10MS%, T30MS%, T100MS%, T300MS%, T1S%, T3S%, T10S%, 
T30S%, T100S%, T300S%, or T1000S% where: 
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US = microseconds 
MS = milliseconds 
S = seconds. 
normalize%: 
an integer that specifies whether or not the vertical scale and offset 


should be applied to the data array of the waveform. Use the pre- 
defined constant TRUE% to apply the scale and offset. Use FALSE% 
to store the scale and offset without applying them to the data. 


status % 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
get7912 


PURPOSE @ 


Acquire a waveform from a Tektronix 7912AD or 7912HB and convert it to 
the SPD waveform format. 


SYNOPSIS 
#include "“tekspd.h" 


ERRORTY PE 

get7912(wave ,wtype,mode,avg_ count, address, timeout ,normalize) 
WAVEFORM **wave; 

short wtype; 

short mode; 

short avg_count; 

short address; 

short timeout; 

short normalize; 


Where: 


wave: 
address of pointer to the newly acquired waveform. 

wtype: 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are W FLOAT and W_DOUBLE. 


mode: 
the Tektronix 7912 acquisition mode to be used. Valid pre-defined con- 
stants are ATC for Average To Center mode, SA for Signal Average 
mode, and EDGE for Edge Detect mode. 


avg count: 
the number of signals the 7912 should average if Signal Average mode 
is chosen. This field is ignored unless the Signal average mode is used. 
Acceptable values for this field are 1, 2, 4, 8, 16, 32, or 64. 


address: 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeout: 
An integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning @ 
a timeout error. Valid values are defined by the constants TNONE, 
T10us, T30us, T100us, T300us, Tims, T3ms, T10ms, T30ms, T100ms, 
T300ms, T1s, T3s, T10s, T30s, T100s, T300s, or T1000s where: 
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uS = microseconds 
ms = milliseconds 
Ss = seconds. 
normalize: 
an integer that specifies whether or not the vertical scale and offset 


should be applied to the data array of the waveform and whether the 
vertical units from the preamble should be attached to the waveform. 
Use the pre-defined constant TRUE to apply the scale and offset and 
to attach the vertical units from the preamble. Use FALSE to store the 
scale and offset without applying them to the data. FALSE also causes 
the string ‘Dig Levels’ to be used for the vertical units. 


DESCRIPTION 


get7912 acquires a waveform from a Tektronix 7912AD or 7912HB using 
the acquisition mode specified by the mode parameter. The function ob- 
tains waveform data from the instrument at the address specified by ad- 
dress, formats the data into an SPD waveform, and puts a pointer to the 
new waveform in *wave. get7912 allocates the memory for the acquired 
waveform. Because of this, *wave should not point to allocated memory 
before calling get7912, otherwise the memory pointed to will be lost to the 
program. If this function is used in a loop to acquire many waveforms, be 


sure to use free_wf to free previously used memory. 
e@ get7912 issues a FATAL under the following conditions: 
Wtype is not equal to W FLOAT or W_DOUBLE. 
Mode is not equal to ATC, SA, or EDGE. 
Avg count is not equal to 1, 2, 4, 8, 16, 32, or 64. 
Address is not equal to POLL or a value between 0 and 29. 
Timeout is not equal to one of the values listed above. 
A GPIB error occurs in acquiring data from the instrument. 
This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 
SEE ALSO 
Include files: 
acg.h 


BASIC FORMAT 


Call bget7912(waveZ ,wtypeZ ,modeZ, avgcountz , ad- 
dressZ,timeoutZ,statusZ) 


Where: 


wave Yo 
integer identifying the newly created waveform 
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wtype Jo 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are WFLOAT% and WDOUBLE“%. 


mode% 
the Tektronix 7912 acquisition mode with which the waveform is to be 
acquired. Valid pre-defined constants are ATC% for Average to Center 
mode, SA% for Signal Average mode, and EDGE®% for Edge Detect 
mode. 


avgcount% 
the number of signals the 7912 should average if Signal Average mode 
is chosen. This field is ignored unless the Signal average mode is used. 
Acceptable values for this field are 1, 2, 4, 8, 16, 32, or 64. 


address % 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeout 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE%, 
T10US%, T30US%, T100US%, T300US%, TIMS%, T3MS%, 
T10MS%, T30MS%, T100MS%, T300MS%, T1S%, T3S%, T10S%, 
T30S%, T100S%, T300S%, or T1000S% where: 


US = microseconds 
MS = milliseconds 
S = seconds. 


nonnalize%: 
an integer that specifies whether or not the vertical scale and offset 
should be applied to the data array of the waveform. Use the pre- 
defined constant TRUE% to apply the scale and offset. Use FALSE% 
to store the scale and offset without applying them to the data. 


status% 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
get7D20 


PURPOSE 


Acquire a waveform from a Tektronix 7D20 and convert it to the SPD 
waveform format. 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 

get/7D20(wave ,wtype, source, address, timeout, normalize) 
WAVEFORM **wave; 

short wtype; 

short source; 

short address; 

short timeout; 

short normalize; 


Where: 


wave: 
address of pointer to the newly acquired waveform. 

wtype: 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are W_FLOAT and W_DOUBLE. 


source: 
the Tektronix 7D20 data source from which the waveform is to be ac- 
quired. Value must be a number from 1 to 6. 


address: 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeout: 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE, 
T10us, T30us, T100us, T300us, Tims, T3ms, T10ms, T30ms, T100ms, 
T300ms, Tis, T3s, T10s, T30s, T100s, T300s, or T1000s where: 


us = microseconds 
ms = milliseconds 
S = seconds. 


normalize: 
an integer that specifies whether or not the vertical scale and offset 
should be applied to the data array of the waveform and whether the 
vertical units from the preamble should be attached to the waveform. 
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Use the pre-defined constant TRUE to apply the scale and offset and 
to attach the vertical units from the preamble. Use FALSE to store the 
scale and offset without applying them to the data. FALSE also causes 
the string ‘Dig Levels’ to be used for the vertical units. 


DESCRIPTION 


get7D20 acquires a waveform from the specified data source of a Tektronix 
7D20. The function obtains preamble and wave data from the instrument 

at the address specified by address, formats the data into an SPD waveform, 
and puts a pointer to the new waveform in *wave. get7D20 allocates the 
memory for the acquired waveform. Because of this, *wave should not 

point to allocated memory before calling get7D20, otherwise the memory 
pointed to will be lost to the program. If this function is used in a loop to ac- 
quire many waveforms, be sure to use free_wf to free previously used 
memory. 


get7D20 issues a FATAL under the following conditions: 
Source is not an integer between 1 and 6. 
Wtype is not equal to W_FLOAT or W_DOUBLE. 
Address is not equal to POLL or a value between 0 and 29. 
Timeout is not equal to one of the values listed above. 
A GPIB error occurs in acquiring data from the instrument. 


This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 


SEE ALSO 


Include files: 
acq.h 


BASIC FORMAT 
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Call bget7D20(waveZ% ,wtype%, source% , address%, timeoutZ, statusZ) 


Where: 


wave % 


integer identifying the newly created waveform 


wtype Yo 


the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are WFLOAT% and WDOUBLE%. 


source Yo 


the Tektronix 7D20 data source from which the waveform is to be ac- 
quired. Value must be a number from 1 to 6. 
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address% 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
@ ment, or else an integer between 0 and 29. 


timeout% 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE%, 
T10US%, T30US%, T100US%, T300US%, TIMS%, T3MS%, 
T10MS%, T30MS%, T100MS%, T300MS%, T1S%, T3S%, T10S%, 
T30S%, T100S%, T300S%, or T1000S% where: 


US = microseconds 
MS = milliseconds 
S = seconds. 


normalize%: 
an integer that specifies whether or not the vertical scale and offset 
should be applied to the data array of the waveform. Use the pre- 
defined constant TRUE% to apply the scale and offset. Use FALSE% 
to store the scale and offset without applying them to the data. 


status 
integer indicating the execution status of the function. Result will be 


© one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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NAME 
getRTD710 


PURPOSE 
Acquire a waveform from a Tektronix RTD710 or RTD710A and convert it 


to the SPD waveform format. 


SYNOPSIS 


9-26 


#include "tekspd.h" 


ERRORTY PE 
getRTD710(wave,wtype, source, location, address, timeout ,normalize) 


WAVEF 
short 
short 
short 
short 
short 
short 


ORM **wave; 
wtype; 
source; 
location; 
address; 
timeout; 
normalize; 


Where: 


wave: 


address of pointer to the newly acquired waveform. 


wtype: 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are W FLOAT and W_ DOUBLE. | 


source: 
the data source from which the waveform is to be acquired. Valid pre- 


defined constants are CH1 and CH2. 


location: 
the memory location from which the waveform should be retrieved. 


Value must be a number from 1 to 32. 


address: 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 


ment, or else an integer between 0 and 29. 


timeout: 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE, 
T10us, T30us, T100us, T300us, Tims, T3ms, T10ms, T30ms, T100ms, 
T300ms, T1s, T3s, T10s, T30s, T100s, T300s, or T1000s where: 


us = microseconds 
ms = milliseconds 
Ss = seconds. 


Signal Processing & Display 


Acquisition 
getRTD710 


normalize: 
An integer that specifies whether or not the vertical scale and offset 
should be applied to the data array of the waveform, and whether the 
, vertical units from the preamble should be attached to the waveform. 

@ Use the pre-defined constant TRUE to apply the scale and offset and 
to attach the vertical units from the preamble. Use FALSE to store the 
scale and offset without applying them to the data. FALSE also causes 
the string ‘Dig Levels’ to be used for the vertical units. 


DESCRIPTION 


getRTD710 acquires a waveform from the specified data source and loca- 
tion of a Tektronix RTD710 or RTD710A. The function obtains preamble 
and wave data from the instrument at the address specified by address, for- 
mats the data into an SPD waveform, and puts a pointer to the new 
waveform in *wave. getRTD710 allocates the memory for the acquired 
waveform. Because of this, *wave should not point to allocated memory 
before calling getRTD710, otherwise the memory pointed to will be lost to 
the program. If this function is used in a loop to acquire many waveforms, 
be sure to use free_wf to free previously used memory. 


getRTD710 issues a FATAL under the following conditions: 
Source is not equal to CH1 or CH2. 
© Location is not a number between 1 and 32. 
Wtype is not equal to W_FLOAT or W_DOUBLE. 
Adadress is not equal to POLL or a value between 0 and 29. 
Timeout is not equal to one of the values listed above. 
A GPIB error occurs in acquiring data from the instrument. 
This function returns an error code (as defined in the spd.h include file) in- 
dicating whether or not it was able to perform correctly. 
SEE ALSO 
Include files: 
acq.h 
BASIC FORMAT 


Call bgetRID710(waveZ ,wtype%Z, source%, location%, ad- 
dressZ,timeoutZ,status%Z) 


Where: 
_ wave % 


integer identifying the newly created waveform 


wtype Yo 
the data type to use for the data array of the acquired waveform. Valid 
pre-defined constants are WFLOAT% and WDOUBLE%. 
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source 7% 
the Tek RTD710 data source from which the waveform is to be ac- 
quired. Valid pre-defined constants are CH1% and CH2%. 


location% 
the memory location from which the waveform should be retrieved. 
Value must be a number from 1 to 32. 


address% | 
GPIB bus address at which to find the instrument. Value must be 
either POLL to specify an automatic search on the bus for the instru- 
ment, or else an integer between 0 and 29. 


timeout% 
an integer that specifies how long the program should wait for a 
response from the GPIB without aborting the acquisition and returning 
a timeout error. Valid values are defined by the constants TNONE%, 
T10US%, T30US%, T100US%, T300US%, TIMS%, T3MS%, 
T10MS%, T30MS%, T100MS%, T300MS%, T1S%, T3S%, T10S%, 
T30S%, T100S%, T300S%, or T1000S% where: 


US = microseconds 


MS = milliseconds 
S = seconds. 


normalize%: 
an integer that specifies whether or not the vertical scale and offset @ 
should be applied to the data array of the waveform. Use the pre- 
defined constant TRUE% to apply the scale and offset. Use FALSE% 
to store the scale and offset without applying them to the data. 
status % 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, or CRASH%. 
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This section of the manual lists the waveform graphics display functions in al- 
phabetical order, with detailed descriptions. 


The description of each function is formatted as follows: 


Name: name of function 
Purpose: tells what the function does 
Synopsis: shows the calling format for the function as follows: 


function name (arguments) 
type declarations 


Description: full description of the function 


BASIC Format: describes the BASIC calling format and differences be- 
tween type declarations. 
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NAME 
gr_addcv 


PURPOSE 
Adds curve to display 


SYNOPSIS 


#include “tekspd.h" 


ERRORTY PE 
gr_addcv (curve _num, x_set, y_set, line color, line_type) 
int curve_num, /* eurve id 0-31 */ 
x_set_num, /* set id for x axis data */ 
y_set_num. /* set id for y axis data */ 
line color, /* color index for this line */ 
line type; /* line type index (l=solid) */ 
DESCRIPTION 


This function adds a curve to an existing display after gr _dsply has already 
been called at least once. Results are not visible until gr_dsply is called 
again. The viewport must not be changed between the call to gr_dsply and 
the call to gr addcv. X_set num andy set _num identify data sets that have 
been previously defined using gr defa, gr deff, gr _defd, or gr defw. 
Pre-defined constants defining line colors and types are defined in tekgr.h. 
The available colors are BLACK, WHITE, RED, GREEN, BLUE, YEL- 
LOW, CYAN, and MAGENTA. The available line types are DEJAG, 
INTRP, INTRP_DEJAG, SOLID, LONG DASH, DOTTED, 
DASH_DOTTED, MED DASHED, DASH1 DOT, or SHORT DASH. 


The function returns GRAPH ERR if there is a problem with the graph; 
NOERROR otherwise. 


BASIC FORMAT 


call bgraddcv (curvnumZ, xset%, yset%, lcolor%, ltypeZ, status2) 


Where: 

curvnum %, the curve number 
ene set id for the x axis 
yset%, set id for the y axis 
lcolor%, line color 


The available colors are BLACK%, WHITE%, RED%, GREENS, 
BLUE%, YELLOW%, CYAN%, and MAGENTA%. 
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Itype%, the line type 


The available line types are DEJAG%, INTRP%, INTRPDEJAG%, 
SOLID%, LONGDASH%, DOTTED%, DASHDOTTED%, MED- 
© DASHED%, DASH1DOT, or SHORTDASH%. 


status Yo execution status of the function 
integer indicating the execution status of the function. Result will be 


one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr addmk 


PURPOSE © 


Add marker curve 
SYNOPSIS 

#include "tekspd.h" 

ERRORTY PE 


gxr_addmk (curve _num, x_set_num, y_set_num, marker_color, 
marker _ type) 


int curve_num, /* curve id 0-31 */ 
x_set_num, /* set id for x axis data */ 
y_set_num, /* set id for y axis data */ 
marker color, /* marker color index */ 
marker type; /* marker type (see VDI Manual) */ 
DESCRIPTION 


This function adds a curve drawn with markers to an existing display after 

gr_dsply has already been called at least once. Results are not visible until 

gr _dsply is called again. The viewport must not be changed between the call 

to gr_dsply and the call to gr addmk. X_set_ num andy set_num identify © 
data sets that have been previously defined using gr _defa, gr deff, gr defd, 

or gr_defw. Marker colors and types are defined in tekgr.h. The available 

colors are BLACK, WHITE, RED, GREEN, BLUE, YELLOW, CYAN, 

and MAGENTA. The available marker types are DOT, STAR, CROS, 

SQUARE, DIAMOND, and X_MRKR. 


The function returns GRAPH ERR if there is a problem with the graph; 
NOERROR otherwise. 


BASIC FORMAT 


call bgraddmk (curvnumZ, xset%, yset%, mkcolor%, mktypeZ, statusZ) 


Where: 

curvnun Yo curve number 
xset%, set id for the x axis 
yset%, set id for the y axis 


mkcolor%, marker color & 


The available colors are BLACK%, WHITE%, RED%, GREENS, 
BLUE%, YELLOW%, CYAN%, and MAGENTA%. 
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mktype%, marker type 


The available marker types are DOT%, CROSS%, STAR%, 
SQUARE%, XMARKR%, and DIAMOND%. 


status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 


gr_autoscale 


PURPOSE ® 


Set axis autoscale mode 


SYNOPSIS 


#include "tekspd.h" 


ERRORTY PE 

gr_autoscale (axis) 

int axis; /* use defined constants X or Y */ 
DESCRIPTION 


This function resets the specified axis to automatic range scaling, which is 
the default state (Gr_reset also resets autoscaling.) 


The function returns PARAM _ ERR if the axis type is invalid; NOERROR 


otherwise. 
BASIC FORMAT 
call bgrautosale (axis%z, status2Z) © 
Where: 
axis%, predefined constant X% or Y%. 
status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH&%, 
GRAPHERR%, or PARAMERR%. 
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NAME 


gr_autotics 


PURPOSE 
Set axis autotick mode 
SYNOPSIS 


#include “tekspd.h" 


ERRORTYPE 

gr_autotics (axis) 

int axis; /* axis specifier, O:x. l:y */ 
DESCRIPTION 


This function resets tick mark generation and selection to automatic, which 
is the default state (Gr_reset also resets automatic tick generation.) 


The function returns PARAM ERR if the axis type is invalid, NOERROR 
otherwise. 


BASIC FORMAT 


call bgrautotics (axis%, statusZ) 


Where: 
axis%, predefined constant X% or Y%. 
status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr_axclr 


PURPOSE = 


Set axes color 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
gr_axclr (axis_ color) 
int axis_color; /* axes color index */ 


DESCRIPTION 


This function sets the color index used for drawing the axes, tick marks, and 
tick mark labels. The default axis color is WHITE. Gr reset restores the 
default axis color. 


This function returns PARAM _ERR if axis_color is < 0; NOERROR 
otherwise. 


BASIC FORMAT 


call bgraxclr (axiscolor%, statusZ) ; © 


Where: 


axiscolor%, axis color 


The available colors are BLACK%, WHITE%, RED%, GREEN%, 
BLUE%, YELLOW%, CYAN%, and MAGENTA%. 


status[o execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR@. 
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NAME 


gr axes 


_ PURPOSE 


Set axes type 


SYNOPSIS 


#include "“tekspd.h" 


ERRORTY PE 

gr_axes (xX_axis type, y_axis_type) 

int x_axis type, /* use constants LIN AXIS or LOG AXIS */ 
y_axis_type; 


DESCRIPTION 


This function sets axis type to /inear-linear, log-linear, or log-log. The default 
axis type is linear-linear. The axis type will be forced to /inear if the mini- 
mum data value for that axis (x_min ory min) is < 0. Gr_reset restores the 
default axis type. Note that when using LOG AXIS for the x axis, it’s best 
not to include the zero index value in the data set (remember, it’s a long 
way from log(0) to log(1)). The function returns PARAM ERR if the 
axis_type is invalid, NOERROR otherwise. 


BASIC FORMAT 


call bgraxes (xaxistype%, yaxistype%Z, statusZ) 


Where: 
xaxistype Zo, X axis type 

pre-defined constant LINAXIS% or LOGAXIS%. 
yaxis%, y axis type 

pre-defined constant LINAXIS% or LOGAXIS%. 
status% execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR“%. 
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NAME 
gr_back 


PURPOSE © 


Set background color 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
gxr_back (r, g, b) 
int r, g, b; /* red, green, and blue values, 
in tenths of a percent (0-1000) */ 


DESCRIPTION 


This function sets the background color for the entire display screen. The 
default background color is BLACK. This is the color corresponding to 
color index 0. Color index 0 is redefined by this call. Gr_reset restores the 
default background color. 


The function returns PARAM ERR if, g, or b are out of range; NOER- 
ROR otherwise. 


BASIC FORMAT r 


call bgrback (rZ, g%, b%, statusZ) 


Where: 

r%, 2%, b% red, green, and blue color mix values in tenths of a per- 
cent. 

status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr box 


6 PURPOSE 


Draw graph box 


SYNOPSIS 
#include "tekspd.h" 


ERRORTY PE 
gxr_box (color) 
int. color: 


DESCRIPTION 


This function draws a box around the graph area bounded by the axes on 
the left and the bottom. The default state for box is "no box". Gr_reset res- 
tores the default box state. 


The available colors are BLACK, WHITE, RED, GREEN, BLUE, YEL- 
LOW, CYAN, and MAGENTA. 


The function returns PARAM ERR if color < 0; NOERROR otherwise. 


@ BASIC FORMAT 


call bgrbox (bcolor%, statusZ) 


Where: 


bcolor%, box color 


The available colors are BLACK%, WHITE%, RED%, GREEN%, 
BLUE%, YELLOW%, CYAN%, and MAGENTA. 


status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr clear 


PURPOSE © 


Clear device 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
gr_clear () 


DESCRIPTION 


This function clears the currently open graphics device; effect depends on 
the type of device in use (displays are cleared, printer page is advanced, 
etc.). 


The function returns PARAM ERR if there is no graphics device open, 
GRAPH ERR if a graphics error has occurred, NOERROR otherwise. 


BASIC FORMAT 
call bgrclear (statusZ) @ 
Where: 
status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr_close 


PURPOSE 

Close device 
SYNOPSIS 

#include "tekspd.h" 


ERRORTY PE 
gr_close() 


DESCRIPTION 


This function closes the currently open graphics device. If the device is the 
DISPLAY device, the screen is cleared and returned to text mode. 


The function returns GRAPH ERR if a graphics error has occurred, 
NOERROR otherwise. 


BASIC FORMAT 
call bgrclose (statusZ) 
Where: 
status Zo status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 


gr curv 


PURPOSE © 


Define curve 


SYNOPSIS 


#include "tekspd.h" 


ERRORTY PE 
gr_curv (curve_num, x_set_id, y_set_id, line _color, line type) 
int curve_num, 7/* curve id 0-31 */ 
x set_id, /* set id for x axis data */ 
y_set_id, /* set id for y axis data */ 
line color, /* color index for this line */ 
line type; /* line type index */ 
DESCRIPTION 


This function defines a curve from the specified data sets. The curve is 

drawn using the specified color and line type. A dejagged line is specified 

by a line_type value of -1, a waveform (interpolated) plot is specified by a 

value of -2, and a dejagged waveform plot is specified by a value of -3. 

Dejagged lines are only displayed on the devices that support more than 64 rd 
colors; it is displayed as a solid line on other devices. 


Line color is defined in tekgr.h and may be one of BLACK, WHITE, RED, 
GREEN, BLUE, YELLOW, CYAN, or MAGENTA. These are the color 
indices as they are defined by gr init. Calling gr_ back during the program 
will redefine the color that index 0 (black by default) is set to. 


Line style is defined in tekgr.h and may be one of DEJAG, INTRP, 
INTRP_DEJAG, SOLID, LONG_DASH, DOTTED, DASH DOTTED, 
MED _DASHED, DASH2_DOT, or SHORT_DASH. 


This function returns PARAM ERR if curve_num, x_set_num, or 
y_set_num is out of range; NOERROR otherwise. 


BASIC FORMAT 


call bgrcurv (curvenumZ, xset%, yset%, lcolor%, ltype%, statusZ) 


Where: 

curvenum %, curve number 

xset%, set id for x-axis data © 
yset%, set id for y axis data 

lcolor%, line color 
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The available colors are BLACK%, WHITE%, RED%, GREEN%, 
BLUE%, YELLOW%, CYAN%, and MAGENTA%. 


Itype%, line type 
@ The available line types are DEJAG%, INTRP%, INTRPDEJAG%, 
SOLID%, LONGDASH%, DOTTED%, DASHDOTTED%, MED- 
DASHED%, DASH1IDOT, or SHORTDASH%. 


status Yo execution status of the function 
integer indicating the execution status of the function. Result will be 


one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr defa 


PURPOSE 
Define automatic data set 


SYNOPSIS 


#include "tekspd.h" 


ERRORTY PE 
gr_defa (set_num, start, end) 
int set_num; /* set id 0-31 */ 
double start, end: /* start and end points of data */ 
DESCRIPTION 


This function defines an automatic data set from the specified starting and 
ending points. This form is convenient for constantly-spaced data for the x 
axis. 


The number of points generated depends on the other data set specified in 
the define curve function. For example, if a curve is defined as a 1024 point 
waveform in data set J, and data set 2 is an automatic set from 0 to 10, then 
1024 values are generated with increment 10/1023. 


The function returns PARAM _ERR if set_num is out of range or if start < 
end; NOERROR otherwise. 


BASIC FORMAT 


call bgerdefa (setnum%Z, start#, end#, statusZ) 


Where: 

setnum %, data set 

stait#, first data point 

end#, last data point 

status %, execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr_defd 


© PURPOSE 


Define double data set 
SYNOPSIS 


#include "tekspd.h" 


ERRORTY PE 

gxr_defd (set_num, npts, darray) 

int set _num; /* set id O-3i */ 

long npts; /* size of data array */ 

double darray[]; /* data */ 
DESCRIPTION 


This function defines a data set from an array of type double data. Any pre- 
viously defined data set with the identifier set_nu is deleted. 


The function returns PARAM ERR if set_num is out of range or npts < = 
0; NOERROR otherwise. 


BASIC FORMAT 


call bgerdefd (setnum%Z, npts%, darray#(0), status2) 


Where: 

setnuin %, data set 

npts%, size of data array 

darray# (0), array of doubles containing the data 
status Yo execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr deff 


PURPOSE ©} 


Define float data set 


SYNOPSIS 


#include "tekspd.h" 


ERRORTY PE 

gxr_deff (set_num, npts, farray) 

int set_num; /* set id 0-31 %/ 

long npts; /* size of data array */ 

float farray[]; /* data */ 
DESCRIPTION 


This function defines a data set from an array of type float data. Any pre- 
viously defined data set with the identifier set_num is deleted. 


The function returns PARAM ERR if set_num is out of range or npts < = 
0; NOERROR otherwise. 


BASIC FORMAT © 


call bgerdeff (setnum%, npts%, farray!(0), statusZ) 


Where: 

setnum]%, the data set 

npts%, size of data array 

farray!(0), array of floating pont numbers containing the data 
status Zo execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr_defw 


6 PURPOSE 


Define waveform data set 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 

gxr_defw (set num, wvform) 
int set_num; /* set id 0-31*/ 
WAVEFORM *wvform; 


DESCRIPTION 


This function defines a data set using the first dimension of the specified 
waveform. Any previously defined data set with the identifier set_num is 
deleted. 


The function returns PARAM ERR if set_num is out of range; NOER- 
ROR otherwise. 


BASIC FORMAT 


call berdefw (setnumZ, wvformZ, status%) 


Where: 

setnum 7%, the data set 

wvforn %, waveform number 

status Yo execution status of the function 


integer indicating the execution status of the function. Result will be 


one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR@. 
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NAME 
gr dev 


PURPOSE @ 


Set graphics device 


SYNOPSIS 


#include "tekspd.h" 


ERRORTY PE 
gr_dev (device) 
char *device; 


DESCRIPTION 


This function opens the specified graphics output device. The string device 
must correspond to a valid CGI logical device name (e.g., DISPLAY, PLOT- 
TER, PRINTER). Any previously opened device is closed. 


This function returns PARAM ERR if the device can’t be opened or is un- 
known; NOERROR otherwise. 


BASIC FORMAT 
call bgerdev (deviceS, statusZ) © 
Where: 
device$ device name 
status Zo execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 

gr_dsply 
PURPOSE 

Output graph 
SYNOPSIS 

#include "tekspd.h" 


ERRORTYPE 
gr_dsply() 


DESCRIPTION 


This function displays or outputs the currently defined graph to the open 
graphics device in the defined viewport. Any of the graph environment or 
label and text functions can affect the graphical output. 


BASIC FORMAT 
call bgrdsply (statusZ) 
Where: 
status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 


gr frame 


PURPOSE | ® 


Draw graph frame 
SYNOPSIS 


#include "“tekspd.h" 


ERRORTY PE 

gr_frame (color) 

int. color: /* color index O-max-colors */ 
DESCRIPTION 


This function permits generation of a frame around the graph. The default 
state for frame is no frame. Gr_reset restores the default frame state. 


The function returns PARAM ERR if color < 0; NOERROR otherwise. 
BASIC FORMAT 
call bgerframe (fcolor%, statueZ) 
Where: © 
fcolor%, frame color 


The available colors are BLACK%, WHITE%, RED%, GREEN%, 
BLUE%, YELLOW%, CYAN%, and MAGENTA%. 


status % execution status of the function 


integer indicating the execution status of the function. Result will be 


one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR&, or PARAMERR%. 
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NAME 
_grid 
PURPOSE 
Display grid 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 

gr_grid (xcolor, xstyle, ycolor, ystyle) 

int xcolor, /* color index of x grid */ 
xstyle, /* Use NO_ GRID, SOLID_GRID, or DOTTED GRID */ 
ycolor, /* color index of y grid */ 
ystyle; /* Use NO_GRID, SOLID_GRID, or DOTTED GRID */ 


DESCRIPTION 


This function draws grid lines parallel to the axes through the major tick 
mark intervals. The default state for grid is NO_GRID. Gr_reset restores the 
default grid state. The available colors are BLACK, WHITE, RED, 
GREEN, BLUE, YELLOW, CYAN, and MAGENTA. 


The function returns PARAM ERR if xcolor, xstyle, ycolor, or ystyle is in- 
valid; NOERROR otherwise. 


BASIC FORMAT 
call bgrgrid (xcolor%, xstylez, ycolor%, ystylez, statusZ) 


Where: 


xcolor%, ycolor%, grid color 


The available colors are BLACK%, WHITE%, RED%, GREEN%, 
BLUE%, YELLOW%, CYAN%, and MAGENTA%. 


status[% execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR“%. 
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NAME 
gr indent 
PURPOSE 


Set axes indent 


SYNOPSIS 


gxr_indent (xindent, yindent) 
int xindent, /* percent axes indent (0-100) */ 
yindent; 


DESCRIPTION 


Axis indentation increases the graphing window to keep ary part of the 
graph from touching the axes. This improves the visibility and appearance 
of the graph. The indentation is measured in percent of a tick interval size. 
The default indentation is 33 (1/3 of a tick interval). Gr_reset restores the 
default indentation. The function returns PARAM ERR if xindent or yin- 
dent is out of range, NOERROR otherwise. 


BASIC FORMAT 


call bgrinden (xindent%, yindent%, status%Z) 


Where: 

xindent%, percent of axis indent - 0 to 100 
yindent%, percent of axis indent - 0 to 100 
status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH&%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr init 


PURPOSE 


Initialize graphing system 


SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
gr_init() 


DESCRIPTION 


gr init 


Initializes the graphing system; it must be the first graphics routine called. 
NDC units refer to Normalized Device Coordinates which range from 0 to 
32767. The following defaults are set by gr init: 


Window 

Window 

Viewport 
Viewport 
Background Color 
Axis Color 

Axis Type 
Autoscale. 
Autotics. 

Indent 

No frame. 

No box. 

No grid. 

Display 

Text note positioning 
Text Color 

Text size 

Text positioning 
Text Rotation 
Text Scale factor 
Title size 

Subtitle size 

Axis label size 
Tick mark label size 


xmin, ymin = Q; 
xmax, ymax = 1. 
xmin, ymin = 0; 
xmax, ymax = 32767. 
black. 

white. 

linear / linear. 


33%. 


data graph. 
viewport relative. 
white. 

797 NDC 

x = left; y = bottom. 
0 degrees 

Li 

10% 

7.59% 

5% 

4.5% 


The function returns GRAPH ERR if there is a graphics error, NOER- 


ROR otherwise. 
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BASIC FORMAT 
call bgrinit (statusZ) 
Where: © 
status [% execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR“%. 
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NAME 
gr _legnd 
PURPOSE 


Define legend 
SYNOPSIS 
#include "tekspd.h" 


ERRORTY PE 
legnd (color, corner) 
int color, corner; 


DESCRIPTION 


This function defines the existence of a curve legend inside the graph area. 
The argument color sets the colors for the text labels defined by gr _/gnst. 
The available colors are defined in tekgr.h and may be one of BLACK, 
RED, BLUE, CYAN, WHITE, GREEN, YELLOW, or MAGENTA. The 
argument commer determines which corner of the graph area in which the 
legend is displayed; predefined valid values are UPPER _ LEFT, 
UPPER_RIGHT, LOWER LEFT, and, LOWER _ RIGHT. The function 
returns PARAM _ERR if comer or color is invalid, -NOERROR otherwise. 


BASIC FORMAT 
call bgrlegnd (lcolor%, corner%, statusZ) 


Where: 


lcolor%, color: 


The available colors are BLACK%, WHITE%, RED%, GREEN%, 
BLUE%, YELLOW%, CYAN%, and MAGENTA%. 


comer%, corner where the legend is displayed: 


Predefined valid values are UPPERLEFT%, UPPERRIGHT%, 
LOWERLEFT%, and LOWERRIGHT%. 


status % execution status of the function: 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 


Signal Processing & Display 10-27 


Waveform Graphics 


gr _Ignst 


NAME 
gr_lgnst 


PURPOSE © 


Define legend string 


SYNOPSIS 
gr_lgnst(curve_ num, string) 
int curve_num; /* curve id O-MAXCURVES-1) */ 
char *string; /* legend label string */ 
DESCRIPTION 


This function defines the text string used in the legend for the specified 
curve. Legend strings are limited to 32 characters. 


Returns PARAM ERR if the curve_nuim is out of range; NOERROR 
otherwise. 


BASIC FORMAT 


call bgrlgnst (curve%, stringS, status%) 


Where: 
curve %, curve number g 


string$, legend string 
status execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 

gr_mrkr 
PURPOSE 

Define marker 
SYNOPSIS 

#include "tekspd.h" 


ERRORTY PE 
gr_mrkr (curve_num, x_set_num, y_set_num, marker color, 
marker type) 


int curve_num, /* curve id 0-31 */ 
x_set_num, /* set id for x axis data */ 
y_set_num, /* set id for y axis data */ 
marker color, /* marker color indes */ 
marker type; /* marker type */ 
DESCRIPTION 


This function defines a curve that is displayed as markers, rather than lines 
(as with gr_curv). The marker colors are defined in tekgr.h and may be one 
of BLACK, RED, BLUE, CYAN, WHITE, GREEN, YELLOW, or 
MAGENTA. The marker types are defined in tekgr.h as DOT, CROSS, 
STAR, SQUARE, X_MRKR, and DIAMOND. The function returns 
PARAM ERR if curve_num, x_set_num, or y_set_num is out of range; 
NOERROR otherwise. 


BASIC FORMAT 


call bgrmrkr (curvnum%Z, xnumZ, ynum%, markcolor%, marktypes) 


Where: 

curvnum %, curve number 

xnum Zo, set number for x axis data 
ynuim %, set number for y axis 
markcolor%, marker color 


The available colors are BLACK%, WHITE%, RED%, GREEN%, 
BLUE%, YELLOW%, CYAN%, and MAGENTA. 


marktype%, marker type 


The available marker types are DOT%, CROSS%, STAR&%, 
SQUARE%, XMARKR%, and DIAMOND%. 
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status Zo execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 


gr Owo 
PURPOSE 
SYNOPSIS 


int 
gr_owo (lindex) 
int index; 


DESCRIPTION 


This function returns the attribute specified by the index for the open work- 
station. There are 66 attributes set by gr dev. They are: 


Index Meaning 


0 Maximum addressable width of screen/plotter in 
rasters/steps assuming a 0 starting point (a resolution of 
640 implies an addressable area of 0-639, so the 
returned value is 639). 


1 Maximum addressable height of screen/plotter in 
rasters/steps assuming a 0 start point (a resolution of 
480 implies an area of 0-479, so the returned value is 
479). 


2 Device coordinates flag where "0" means a device 
capable of producing a precisely scaled image (typically 
plotters and printers) and "1" means a device that is not 
capable of a precisely scaled image (CRTs). 


3 Width of one pel (plotter step) in micrometers. 

4 Height of one pel (plotter step) in micrometers. 

5 Number of character heights (0 = continuous scaling). 

6 Number of line types (0 = device is not capable of 
graphics). 

7 Number of line widths. 

8 Number of marker types 

9 Number of marker sizes (0 = continuous scaling). 

10 Number of graphic text fonts. 

11 Number of patterns. 

12 Number of hatch types. 
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13 


14 
15-24 


25-35 


35 
36 
a7 
38 
39 


40 
41 
42 
43 
aa 


10-52 


Number of predefined colors (at least 2, even for a 
monochrome device). This is the number of colors that 
can be displayed on the device simultaneously. 


Number of Generalized Drawing Primitives (GDP). 


List of GDPs (up to 10 allowed): 


1 = bar 

2 = arc 

3 = pie slice 
4 = circle 


Attribute set associated with each GDP: 


-1 = GDP does not exist 


0 = polyline 

1 = polymarker 
2 = text 

3 = fill area 

4 = none 

5 = other 


Color capability flag (0 = no, 1 = yes). 
Text rotation capability (0 = no, 1 = yes). 
Fill area capability (0 = no, 1 = yes). 

Pel operation capability (0 = no, 1 = yes) 


Total number of colors the device can display. This may 
be larger than the number the device can display simul- 
taneously. 


0 = Continuous device 
2 = Monochrome (black and white) 
2 = Number of colors available 


Locator capability flag (0 = no, 1 = yes). 
Valuator capability flag (0 = no, 1 = yes). 
Number of choices available (1 to n). 
String input capability (0 = no, 1 = yes). 
Work-station type 


0 = output only 

1 = input only 

2 = input/output 

3 = device-independent segment storage 
4 = metafile output 

5 = other 
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45 | Device type: 
0 = CRT 


1=plotter — 
®& 2 = printer 
| 3 = camera/film recorder 

4 = metafile output 
5S = other 

46 Number of writing modes available. 

47 Highest level of input mode available (0 = none, 1 = re- 
quest, 2 = sample). 

48 Text alignment capability flag (0 = no, 1 =yes). 

49 Inking capability flag as output echo device (0 = no, 1 
= yes). 

50 Rubberbanding capability flag as an output echo device: 
0 = no rubberbanking capability 


1 = capable of rubberbank lines 
2 = capable of rubberband lines and rectangles 


51 Maximum addressable NDC unit coordinate on x-axis. 
This value is filled in based on the coordinate transfor- 
mation mode selected. 


52 Maximum addressable NDC unit coordinate on y-axis. 
This value is filled in based on the coordinate transfor- 
mation mode selected. 


53-57 Version of the driver. This is an DCE character string 
that represents the version of the driver in the following 
form: wll where wy is the actual version and Il is the 


level. 
58-59 Reserved. 
60 Minimum graphic character height in NDC units. 
61 Maximum graphic character height in NDC units. 
62 Minimum line width in NDC units. 
63 Maximum line width in NDC units. 
@ 64 Minimum marker height in NDC units. 
65 Maximum marker height in NDC units. 


The function returns the value if successful, or PARAM _ ERR. 
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BASIC FORMAT 
call bgrowo (index%, answerz) " 
Where: 6 
index%, attribute number 
answero, attribute as described above 
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NAME 
gr pause 
PURPOSE 
Pause 
SYNOPSIS 


#include "tekspd.h" 


ERRORTY PE 
gr_pause () 


DESCRIPTION 


This function waits for the ENTER key to be pressed. It is usually used 
before gr close to allow inspection of the graph on the display because 
gr_close clears the display and resets the cursor addressing mode. The func- 
tion returns GRAPH ERR if there is a graphics error, NOERROR other- 
wise. 


BASIC FORMAT 
call bgrpause (statusZ) 
Where: 
status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR&%. 
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NAME 


gr_reset 


PURPOSE 6 


Reset graph 
SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 
gr_reset() 


DESCRIPTION 

This function removes all data, curve, titles, and labels from the current graph 
definition. NDC units refer to Normalized Device Coordinates which range from 
0 to 32767. The following defaults are set by gr reset: 


Window xmin, ymin = 0 
Window xmax, ymax = 1 
Viewport xmin, ymin = 0 
Viewport xmax, ymax = 32767 
Background Color black 

Axis Color white 

Axis Type linear /linear 
Autoscale 

Autotics 

Indent 33% 

Noframe 

No box 

No grid 

Display data graph 

Text note positioning viewport relative 
Text rotation 0 degrees 

Text scale factor 1 

Title size 10% 

Subtitle size 7.5% 

Axis label size 5% 


Tick mark label size 45% 


The function returns GRAPH ERR if there is a graphics error, NOER- 
ROR otherwise. 


BASIC FORMAT G 


call bgrreset (statusZ) 
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Where: 
status % status of the function 
integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 


GRAPHERR%, or PARAMERR%. 
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NAME 


gr size 


PURPOSE 
Set title/label size 


SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 

gr_size (title, subtitle, axis_lab, tick_lab) 
double title; 

double subtitle; 

double axis_lab; 

double tick_lab; 


DESCRIPTION 


This function sets the size of the title, subtitle, axis labels, and tick labels as 
a percentage of the "y" viewport dimension. The total of all percentages 
must be <75%. The values set by gr init are: 


Title = 10% 

Subtitle = 7.5% 

Axis = 5% 

Tick = 4.5% 
The function returns PARAM ERR if the parameters are not in the range 
0 - 75, or if their total > = 75, or NOERROR otherwise. 


BASIC FORMAT 


call bgrsize (ticper#, axlabper#, subper#, titlper#, statusZ) 


Where: 

ticper#, percent size of tic label 
axlabper#, percent size of axis labels 
subper#, percent size of subtitle 
tutleper#, percent size of title 

status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr_stitl 

PURPOSE 
Subtitle 

SYNOPSIS 
#include "“tekspd.h" 
ERRORTY PE 
gr_stitl(subtitle, color) 


char *subtitle; 
int. color: 


DESCRIPTION 


This function places a subtitle in smaller text below the title. The default 
subtitle size is 7.5% of the y viewport dimension. This default is restored 
when gr reset is called. The function returns PARAM _ERR if the color < 
0; NOERROR otherwise. 


BASIC FORMAT 


call bgrstitl (subtitleS, tcolor%, status) 


Where: 
subtitle$, subtitle string 
tcolor%, subtitle color 


The available colors are BLACK%, WHITE%, RED%, GREEN%, 
BLUE%, YELLOW%, CYAN%, and MAGENTA%. 


status Zo execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 


gr text 


PURPOSE 
Text note 
SYNOPSIS 


gr_text (note num, string, xpos, ypos, height, color, xalign, 
yalign, angle) 


int note num; /* note id 0-31 */ 

char *string; 

int xpos, ypos; /* starting position, 0-32767 on each axis */ 
int height; /* height in NDC units */ 

int color; /* color index */ 

int Salis: /* x alignment */ 

int yalign; /* y alignment */ 

int angle; /* angle of rotation around the alignment point, 


in tenths of a degree */ 


DESCRIPTION 


This function allows an arbitrary text string to be placed on the graphing 
display at position (xpos, ypos). The x and y alignment parameters specify 
the position of the point (xpos, ypos) relative to string. For example, xalign 
= RIGHT JUST, yalign = BOTTOM_JUST means that string will be to 
the upper left of the point (xpos, ypos). The position is, by default, relative 
to the entire display; that is, 0,0 is the lower left corner of the screen. 


However, if a text-only graph is specified using gr type, or if viewport-rela- 
tive is set using gr txorg, the text is positioned relative to the current view- 
port. (The point 0,0 is the lower left corner of the current viewport, set by 
the last call to gr_vwot.) 


Color is defined in tekgr.h and may be one of BLACK, RED, BLUE, 
GREEN, CYAN, WHITE, YELLOW, or MAGENTA. The default value 
for color is WHITE. Xalign may be one of LEFT_JUST, CENTER JUST, 
RIGHT JUST while yalign may be one of BOTTOM _JUST, CEN- 

TER . JUST, or TOP _JUST. Rotation > = 0 and <= 3600. The default 
value for yalign is BOTTOM aro, 


The function returns PARAM ERR if any parameter is invalid; NOER- 
ROR otherwise. 


BASIC FORMAT 


call bgrtext (notenumZ, textS, xpos%, ypos%, height%, colorZ, 
xalign%, yalign%, angle%, statusZ) 


10-40 Signal Processing & Display 


Waveform Graphics 


gr text 
Where: 
notenum %, the note number 
text$, text note string 


xpos%, ypos%, starting position 
height%, height of note in NDC units 
tcolor%, note color 


The available colors are BLACK%, WHITE%, RED%, GREEN%, 
BLUE%, YELLOW%, CYAN%, and MAGENTA. 


xalign %, note alignment on the x axis 
LEFTJUST%, CENTERJUST%, or RIGHTJUST% 
yalign %, note alignment on the y axis 
BOTTOMJUST%, CENTERJUST%, or TOPJUST%. 
angle %, angle of rotation around the alignment point in tenths 
of a degree 
status T% execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR“%. 
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NAME 
gr title 


PURPOSE ® 


Title 
SYNOPSIS 


#include "“tekspd.h" 


ERRORTY PE 

gr_title (title, color) 
char *title; 

int. color: 


DESCRIPTION 


This function places a centered title along the top of the graph. The default 
title size is 10% of the y viewport dimension. This default is restored when 
gr_reset is called. 


The function returns PARAM ERR if color < 0; NOERROR otherwise. 


BASIC FORMAT 
call bgrtitle (titleS, tcolor%, statusZ) & 
Where: 
title, title string 
tcolor%, title color 


The available colors are BLACK%, WHITE%, RED%, GREEN%, 
BLUE%, YELLOW%, CYAN%, and MAGENTA%. 


status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr_txorg 


® PURPOSE 


Set text origin mode 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
gr_txorg (org mode) 
int org_mode; /* text origin mode */ 


DESCRIPTION 


This function determines the origin for text notes defined using gr text. By 
default, the coordinates are relative to the entire display. However, this 
function and gr type (text_only) cause the coordinates to be interpreted rela- 
tive to the currently defined viewport. 

Org_mode is one of XY_VWPORT_ RELATIVE or XY_DIS- 

PLAY RELATIVE. 


The function returns PARAM ERROR if org_mode is invalid; NOER- 
ROR otherwise. 


BASIC FORMAT 


call bgrtxorg (orgmodez, statusZ) 


Where: 
orgmode%, identifying the text note origin 

One of XYVWPORTRELATIVE% or XYDISPLAYRELATIVE%. 
status Zo execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr_type 

PURPOSE 6 
Set graph type 

SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 
gr_type (gtype) 
int gtype; /* graph type */ 


DESCRIPTION 


This function sets the graph type to data-graph or text-only mode on text 
defined using gr text. The text origin mode is set to viewport-relative, this 
can be overridden using gr_txorg. Gtype should be one of DIS- 

PLAY GRAPH or TEXT ONLY. 


The function returns PARAM _ ERR if gtype is invalid, NOERROR other- 
wise. 


BASIC FORMAT G 
call bgrtype (gtype%, status2Z) 


Where: 
gtype%, graph type 
DISPLAYGRAPH% or TEXTONLY%. 


status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH&%, 
GRAPHERR%, or PARAMERR%. 
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NAME 


gr_uncurv 


© PURPOSE 


Undefine curve 


SYNOPSIS 
#include "tekspd.h" 


ERRORTY PE 
gr_uncurv (curve_num) 
int curve_num; /* curve id 0-31 */ 


DESCRIPTION 


This function removes a curve definition from the currently defined graph. 
A curve_nuim value of -1 removes ALL curve definitions. 


The function returns PARAM ERR if curve_nuim is out of range and not 
set to -1; NOERROR otherwise. 


BASIC FORMAT 
call bgruncur (curvnumZ, statusZ) 
© Where: 
curvnuin Zo, curve number 
status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr undef 


PURPOSE © 


Undefine data set 


SYNOPSIS 


#include "tekspd.h" 


ERRORTY PE 
gr_undef (set_num) 
int set_num; /* set id 0-31 */ 


DESCRIPTION 


This function removes the specified data set from the data graphing set 
storage area. If set_mwm does not exist and is not set to -1, ALL data sets 
are deleted. 


This function returns PARAM ERR if set_num does not exist and is not 
set to -1; NOERROR otherwise. 


BASIC FORMAT 
Call bgrundef (setnumZ, status2Z) Go 
Where: 
setnum%, data set number 
status Z% execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr update 
PURPOSE 
Update graph 
SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 
gr_update () 
DESCRIPTION 


This function clears the area of the viewport containing the plotted curve 
and redraws the graph data leaving the axes, title, and axis label text un- 
changed. The grid is also cleared and redrawn. Gr _dsply must have been 
previously called. This function only makes sense on a video display. 


The data and curve definitions may have changed since the gr_dsply func- 
tion call and any data outside the window determined by the previous dis- 
play will be clipped (not displayed). 


This function returns GRAPH ERR if no device is open, NOERROR 
otherwise. 


BASIC FORMAT 
call bgrupdat (statusZ) 
Where: 
status execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr_vwpt 
PURPOSE -~ 
Define viewport 
SYNOPSIS 
gr_vwpt (xmin, ymin, xmax, ymax) 
int xmin, ymin, /* lower left corner */ 
xmax, ymax; /* upper right corner, in NDC units */ 
DESCRIPTION 


This function defines the area of the output surface to be used for the 
graph. NDC units (0-32767) are used. By default, the entire output surface 
is used. (xmin, ymin = 0, xmax, ymax = 32767.) Only the viewport area is 
cleared when a graph is displayed. 


If the parameters specified are out of range, they are adjusted to be on the 
boundary of the range. If xmin > xmax or ymin > ymax, the min and max 
values are swapped. 


Returns PARAM ERR if xmin = xmax or ymin = ymax, NOERROR 

otherwise. 6 
BASIC FORMAT 

call bevwpt (xmin%, ymin%, xmax%, ymax%Z, status) 

Where: 

xminZ, ymin%, — lower left corner in NDC units 

xmax%, ynax%, upper right corner in NDC units 


status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr xlabl 


© PURPOSE 


X-axis label 
SYNOPSIS 
#include "“tekspd.h" 


ERRORTYPE 

gr_xlabl (label, color) 
char *label; 

ink color: 


DESCRIPTION 


This function places a centered label under the x axis. The default axis label 
size is 5% of the y viewport dimension. This default is restored when 
gr_reset is called. The available colors are defined in tekgr.h and may be one 
of BLACK, RED, BLUE, CYAN, WHITE, GREEN, YELLOW, or 
MAGENTA. 


The function returns PARAM ERR if color < 0, or NOERROR otherwise. 


® BASIC FORMAT 


call bgrxlabe (labelS, lcolor%, statusZ) 


Where: 
label§, x axis label string 
lcolor%, integer indicating the label color 


The available colors are BLACK%, WHITE%, RED%, GREEN%, 
BLUE%, YELLOW%, CYAN%, and MAGENTA%. 


status [% execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR“%. 
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NAME 


gr_xrang 


PURPOSE G& 


Set x-axis range 


SYNOPSIS 
#include "tekspd.h" 


ERRORTY PE 
gr_xrang (xmin, xmax) 
double, xmin, xmax; 


DESCRIPTION 


This function sets the x axis graph limits. When this function is not called, 
the x axis range is automatically determined from the curve data. The 
default setting for axis range is “autoscale". Gr_reset removes the effect of 
this function and returns the scaling to “autoscale”. 


The function returns PARAM ERR if xmax < = xmin; NOERROR other- 


wise. 
BASIC FORMAT © 
call bgxrang (xmin#, xmax#, statusZ) 
Where: 
xmin#, xinax#, X axis Minimum and maximum range 
status Yo execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR@. 
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NAME 


gr xtics 


6 PURPOSE 


Set x-axis ticks 
SYNOPSIS 
#include "tekspd.h" 


ERRORTY PE 
gr_xtics (major, minor) 
double major, minor; 


DESCRIPTION 


This function sets the tick mark spacing on the x axis. The major tick marks 
are labeled; the minor ticks are shorter and not labeled. Automatic tick 
generation is the default and generates approximately five major ticks per 
axis. Gr_reset removes the effect of this function and returns the tick genera- 
tion to "autotic”. 


This function returns PARAM _ ERR if major < minor; NOERROR other- 
6 wise. 
BASIC FORMAT 


call bgxtics (major#, minor#, statusZ) 


Where: 

major#, major tick mark spacing 
minor#, minor tick mark spacing 

status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr_ylabl 

PURPOSE 2 
Y-axis label 

SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 

gxr_ylabl (label, color) 
char *label; 

int color: 


DESCRIPTION 


This function places a label at 90 degrees, parallel to the y axis. The default 
axis label size is 5% of the y viewport dimension. This default is restored 
when gr reset is called. The available colors are defined in teAgr.h and may 
be one of BLACK, RED, BLUE, CYAN, WHITE, GREEN, YELLOW, or 
MAGENTA. 


The function returns PARAM ERR if color < 0, NOERROR otherwise. @ 
BASIC FORMAT 


call bgrylabe (labelS, lcolor%, statusZ) 


Where: 
label§, y axis label string 
Icolor%, label color 


The available colors are BLACK%, WHITE%, RED%, GREEN%, 
BLUE%, YELLOW%, CYAN%, and MAGENTA%. 


status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 

gr_yrang 
PURPOSE 

Set y-axis range 
SYNOPSIS 


#include "tekspd.h" 


ERRORTYPE 


gxr_yrang (ymin, ymax) 
double ymin, ymax. 


DESCRIPTION 


This function sets the y axis graph limits. When this function is not called, 
the y axis range is automatically determined from the curve data. The 
default setting for axis range is “autoscale". Gr_reset removes the effect of 
this function and returns the scaling to "autoscale". 


The function returns PARAM ERR if ymax < = ymin; NOERROR other- 
wISe. 


BASIC FORMAT 
call bgryrang (ymin#, ymax#, statusZ) 
Where: 
ynin#, ynax# y axis minimum and maximum range 
status Yo execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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NAME 
gr_ytics 


PURPOSE © 


Set y axis tick marks 
SYNOPSIS 
#include "tekspd.h" 


ERRORTYPE 
gr_ytics (major, minor) 
double major, minor; 


DESCRIPTION 


This function sets the tick mark spacing on the y axis. The major tick marks 
are labeled; the minor ticks are shorter and not labeled. Automatic tick 
generation is the default and generates approximately five major ticks per 
axis. Gr-reset removes the effect of this function and returns the tick genera- 
tion to "autotic”. 


This function returns PARAM ERR if major < minor, NOERROR other- 
wise. 
BASIC FORMAT @ 


call bgrytics (major#, minor#, statusZ) 


Where: 

major#, major tick mark spacing 
minor#, minor tick mark spacing 

status % execution status of the function 


integer indicating the execution status of the function. Result will be 
one of NOERROR%, WARN%, FATAL%, CRASH%, 
GRAPHERR%, or PARAMERR%. 
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Section 11 


Waveform Structure 
Access 


This section addresses accessing and manipulating waveform data structures and 
the information in them. This is provided by means of "C" language macros that 
reference data structure members. For most users, the need to do this will be 
confined to setting and reading labels, titles, scales, offsets, etc. (Only those 
programmers who are extending the package by adding their own functions will 
care about more detailed accesss, but it is available.) The "C" macros are listed 
and described in Appendix C under the section that lists the "C" header file 
wav.h. Attaching string data (e.g., title strings) to a waveform data structure is 
best done with the library functions (e.g., wf title() from "C" for bwftitle() from 
BASIC) because those functions provide memory allocation options as well as 
access to the waveform structure. 


Since using the macros is not directly possible from BASIC, interface functions 
are provided for sixteen of the macros--those that make sense to use from 
BASIC. (Most "C" programs won’t use any of the others, either.) This section 
describes those BASIC interface functions--there are more than sixteen because 
some macros spawn two functions, one to read data, another to write data. The 
function names are derived from the macro names. 
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NAME 
bdimlabel 


PURPOSE 


Read dimension label 


SYNOPSIS 


call bdimlabel: (wavzZ, dimnumZ, labelS, strlenZ%, statusZ) 


DESCRIPTION 
Read and return the specified dimension label. 


wav 
integer identifying the waveform 


dimnuin QZ 
the dimension number 


label$ 
the dimension label string 


strlen % 
the length of the label string 


status % 
a returned error status value of NOERROR% or FATAL% 


NOTE 


Use the bwfdlabel() function to set a dimension length. 


11-2 Signal Processing & Display 


Waveform Structure Access 


bdimlen 


NAME 


bdimlen 


PURPOSE 
Read dimension length 


SYNOPSIS 


call bdimeln (wavez%, dimnum%Z, dimlen&, statusZ) 


DESCRIPTION 
Read and return the specified dimension length. 
wave Yo 
integer identifying the waveform 


dimnuin % 
the dimension number 


dimlen& 
the length of the dimension 


status Yo | 
a returned error status value of NOERROR% or FATAL% 
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NAME 
brdimoffset 


PURPOSE © 


Read dimension axis offset 
SYNOPSIS 


call brdimoffset (wave%, dimnumZ, offset#, statusZ) 


DESCRIPTION 
Read and return the specified dimension axis offset. 
wave Yo 
an integer identifying the waveform 


dimnuin 
the dimension number 


Offset# 
the dimension offset 


status[% 
a returned error status value of NOERROR% or FATAL% 
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NAME 
bwdimoffset 


© PURPOSE 
Write dimension axis offset 


SYNOPSIS 


call bwdimoffset (wavez, dimnumZ, offset#, statusZ) 


DESCRIPTION 
Write the axis offset for the specified dimension. 
wave Yo 
an integer identifying the waveform 


dimnum 9% 
the dimension number 


offset# 
the axis offset 


status % 
a returned error status value of NOERROR% or FATAL% 
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NAME 


brdimscale 


PURPOSE © 


Read dimension scale factor 


SYNOPSIS 


call brdimscale (wave%, dimnumZ, scale#, statusZ) 


DESCRIPTION 
Read and return the specified dimension scale factor. 


wave Jo 
an integer identifying the waveform 


dimnuim Yo 
the dimension number 


scale# 
the dimension scale factor 


status Zo 
a returned error status value of NOERROR% or FATAL% 
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NAME 


bwdimscale 


PURPOSE 
Write dimension scale factor 


SYNOPSIS 


call bwdimscale (wavezZ, dimnumZ, scale#, status2Z) 


DESCRIPTION 
Write the specified dimension scale factor. 


wave Yo 
an integer identifying the waveform 


dunnuimn% 
the dimension number 


scale# 
the dimension scale factor 


status % 
a returned error status value of NOERROR% or FATAL% 
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NAME 


bdimunits 


PURPOSE ® 
Read dimension units string 


SYNOPSIS 


call bdimunits (wave%, dimnumZ, unitsS, strlenz, statusZ) 


DESCRIPTION 
Read and return the specified dimension units string. 


wave % 
an integer identifying the waveform 


dimnuin % 
the dimension number 


units 
the dimension units string 


strlen % 
the length of the units string 


status % 
a returned error status value of NOERROR% or FATAL% © 


NOTE 


Use the bwfdunits() function to set the dimension units. 
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NAME 
bnotesptr 


© PURPOSE 
Read waveform notes string 


SYNOPSIS 


call bnotesptr (wave%, notesS, strlen%z, statusZ) 


DESCRIPTION 
Read and return the specified waveform notes string. 


wave % 
an integer identifying the waveform 


label$ 
the waveform notes string 


strlen % 
the length of the notes string 


status % 
a returned error status value of NOERROR% or FATAL% 


NOTE 


Use the bwfnotes() function to set the notes string. 
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NAME 
btitleptr 


PURPOSE @ 


Read waveform title 


SYNOPSIS 


call btitleptr (wave%, titleS, strlen%, status%) 


DESCRIPTION 
Read and return the specified waveform title. 
wave Yo 
an integer identifying the waveform 


title$ 
the waveform title string 


strlen Zo 
the length of the label string 


status % 
a returned error status value of NOERROR% or FATAL% 


NOTE © 


Use the bwftitle() function to set the waveform title. 
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NAME 
btuplabel 


PURPOSE 
Read tuple label 


SYNOPSIS 


call btuplabel (wave%, tupnumZ, labeS, strlenz, statusZ) 


DESCRIPTION 
Read and return the specified tuple label. 
wave Yo 
an integer identifying the waveform 


tupnuimn Yo 

the tuple number 
label$ 

the tuple label string 


strlen % 
the length of the label string 


status Vo 
a returned error status value of NOERROR% or FATAL% 
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NAME 
brtupoffset 


PURPOSE © 
Read tuple offset 


SYNOPSIS 


call brtupoffset (wave%, tupnum%Z, offset#, statusZ) 


DESCRIPTION 
Read and return the specified tuple offset. 


wave Yo 
an integer identifying the waveform 


tupnum 
the tuple number 


offset# 
the offset 


status Yo 


a returned error status value of NOERROR% or FATAL% 
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NAME 
bwtupoffset 


© PURPOSE 
Write tuple offset 


SYNOPSIS 


call bwtupoffset (wavez, tupnumZ, offset#, status2) 


DESCRIPTION 
Write the specified tuple offset. 


wave Yo 
an integer identifying the waveform 


tupnum Yo 
the tuple number 


offset# 
the tuple offset 


status % 
a returned error status value of NOERROR% or FATAL% 


Signal Processing & Display 11-15 


Waveform Structure Access 


brtupscale 


NAME 
brtupscale 


PURPOSE © 
Read tuple scale 


SYNOPSIS 


call brtupscale (wave%, tupnumZ, scale#, status) 


DESCRIPTION 
Read and return the specified tuple scale. 


wave Yo 
an integer identifying the waveform 


tupnuimn Yo 
the tuple number 


scale# 
the tuple scale factor 


status % 
a returned error status value of NOERROR% or FATAL% 
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NAME 
bwtupscale 


@ PURPOSE 
Write tuple scale factor 


SYNOPSIS 


call bwtupscale (wave%Z, tupnumZ, scale#, statusZ) 


DESCRIPTION 
Read and return the specified tuple label. 


wave Yo 
an integer identifying the waveform 


tupnuim 
the tuple number 


scale# 
the tuple scale factor 


status Zo 
a returned error status value of NOERROR% or FATAL% 
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NAME 
btuptype 


PURPOSE -_ 
Read tuple type 


SYNOPSIS 


call btuptype (wave%, tupnumZ, tuptupes, statuss) 


DESCRIPTION 


Read and return the specified tuple type. Note that this function does not 
have a corresponding write function since the data type of a waveform can- 
not be changed after it is created. 
wave % 
an integer identifying the waveform 
tupnum Yo 
the tuple number 
tuptype Zo 
the returned tuple type which will be one of WSHORT%, WLONG%, 
WFLOAT%, or WDOUBLE%. 


status % © 
a returned error status value of NOERROR% or FATAL& 
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NAME 
btupunits 


PURPOSE 
Read tuple units string 


SYNOPSIS 


call btupunits (wave%, tupnumZ, unitsS, strlenZ, statusZ) 


DESCRIPTION 
Read and return the specified tuple units. 


wave % 
an integer identifying the waveform 


tupnum 
the tuple number 


units$ 
the tuple units string 


strlen % 
the length of the units string 


status % 
a returned error status value of NOERROR% or FATAL% 


NOTE 


Use the bwftunits() function to set tuple units. 
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NAME 


bwavedim 


PURPOSE @ 


Read number of dimensions in a waveform 
SYNOPSIS 


call bwavedim (wave%, dimnumZ, statusZ) 


DESCRIPTION 
Read and return the number of dimensions in a specified waveform. 
wave Yo 
an integer identifying the waveform 
dimnuin % 
the number of dimensions 


status % 


a returned error status value of NOERROR% or FATAL% 
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NAME 


bwavelen 


@ PURPOSE 
Read number of elements in the first dimension of a waveform 
SYNOPSIS 


call bwavelen (wave%, numel&, statusZ) 


DESCRIPTION 
Read the number of elements in the first dimension of a waveform. 
wave % 
an integer identifying the waveform 


numel& 
the number of elements 


status % 


a returned error status value of NOERROR% or FATAL% 
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NAME 


bwavetuple 


PURPOSE a 


Read the number of tuples in a waveform 
SYNOPSIS 
call bwavetuple (wavez, numtupZ, status) 


DESCRIPTION 
Read and return the number of tuples in a waveform. 


wave Yo 
an integer identifying the waveform 


numtup 
the number of tuples 


status T% 
a returned error status value of NOERROR% or FATAL% 
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NAME 
bwavetype 
PURPOSE 


Read the type of the first tuple in a waveform 
SYNOPSIS 


call bwavetype (wave%, tuptype%, statusZ) 


DESCRIPTION 
Read and return the type of the first tuple in a waveform. 
wave % 
an integer identifying the waveform 


tuptype% 
the type of the first tuple in the waveform. The value returned will be 


one of WSHORT%, WLONG%, WFLOAT, WDOUBLE%. 


status Zo 
a returned error status value of NOERROR% or FATAL% 
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Appendix A 
Glossary 


allocate a waveform - Reserve space in memory for a waveform data structure 
and associated data. 


array - A collection of data, each having a common name, data-range, and data 
type. An array can be defined as a short or long integer or a float or double 
float array, and can be further classified as one-dimensional or multi- dimen- 
sional depending on how the array elements are indexed. 


autocorrelation- The process of correlating a signal with itself. (See "correla- 
tion" and "cross-correlation.) 


convolution - The process, given the system impulse response, of determining 
the output wave shape for a given input wave shape. Convolution can be per- 
formed by computing the Fast Fourier Transform of each signal to be con- 
volved, multiplying these two Fast Fourier Transform results, and then 
computing the Inverse Fast Fourier Transform of the product. 


correlation - A mathematical operation that describes the similarity between 
two waveforms as a function of the delay (time-shift). Correlation can be 
thought of as successively shifting one signal (by some horizontal increment), 
forming the product of the two signals, and integrating the product. Correlation 
can be achieved by computing the Fast Fourier Transform of each signal to be 
correlated, then forming a complex-conjugate product from the Fast Fourier 
Transform results, and finally taking the Inverse Fast Fourier Transform of the 
product. 


data sampling interval - The numerical difference in acquisition time (or dis- 
tance) between two successive data samples in a digitized waveform. Also some- 
times called the honzontal scale factor. 


deallocate a waveform - Free memory previously occupied by the waveform data 
structure. 


differentiation - The process of finding the slope of a waveform at a specified 
location. 
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distal - Of or pertaining to a region remote from a first state or region of origin. 
Of the three conventional pulse crossing level locations, the distal point is the 
one most distant from the selected point of origin. Usually, the 90% level cross- 
ing location. 


Fast Fourier Transform (FFT) - An algorithm for converting a signal from the 
time domain to the frequency domain in an efficient manner. 


FIR - Finite Impulse Response. An FIR filter has an impulse h(t) that ter- 
minates at some finite time, i.e., h(n * delta T) = 0 for all n greater than some 
value M. These filters may be represented as a finite set of L weighted impulses 
scparatcd by delta T; the impulse response is then of length L * delta T. FIR fil- 
ters are usually implemented as a weighted sum of L time-delayed waveform 
samples. No feedback is used. 


frequency domain - The representation of a signal such that its amplitude is ex- 
pressed as a function of frequency. 


IIR - Infinite Impulse Response. An IIR filter has an impulse response that 
continues forever. These filters are usually implemented with feedback. 


integration - The process of finding the area of a waveform. 


Inverse Fast Fourier Transform (IFFT) - An algorithm for converting a signal 
from the frequency domain to the time domain in an efficient manner. 


leakage - The introduction of erroneous spectral components in the frequency 
domain representation of a waveform during transformation from the time 
domain. Leakage occurs when a time domain record of a periodic signal con- 
tains a non-integral number of cycles and that record is transformed to the fre- 
quency domain. The transformation (necessarily) makes some invalid 
assumptions about exact integral periodicity that lead to attenuation and 
broadening of the spectral lines. In the displayed spectrum, it appears that ener- 
gy has leaked from one spectral line to an adjacent one - hence, the term 
leakage. Leakage can be reduced by windowing the time domain waveform by a 
windowing function. 


mesial - Of or pertaining to the region between the proximal and distal regions. 
Of the three conventional pulse crossing locations, this is between the proximal 
(usually 10%) level and the distal (usually 90%) level locations. Usually, the 
50% level crossing location. 


polar form- A frequency domain representation in which the spectral com- 
ponents are expressed in terms of magnitude and phase (See "rectangular form"). 


proximal- Of or pertaining to a region near to a first state or region of origin. 


rectangular form- A frequency domain representation in which the spectral com- 
ponents are expressed as real and imaginary values. 
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root-mean-square value- The effective value of a varying or alternating voltage. 
It is equivalent to that value that would produce the same power as if a con- 
tinuous voltage of that value were applied to a pure resistance. 


signal averaging- The process of acquiring a given number of whole-waveform 
records, summing them, and dividing by the number of acquired waveforms. Sig- 
nal averaging improves the signal-to-noise ratio when the waveforms have noise 
but are otherwise identical. 


subordinate waveform- A waveform data structure that is linked to an original 
waveform data structure. In general, a subordinate waveform has a reduced 
number of dimensions, tuples, and dimension lengths, or some combination of 
these. 


taper- To apply a windowing function over a portion of a waveform or the entire 
waveform. The portion is usually expressed as a fraction or percentage of the 
waveform’s length. 


ticmark- One of several equally spaced dashes marked on an axis to denote a 
particular value. 


time domain- The representation of a signal such that the signal amplitude is ex- 
pressed as a function of time. 


tuple- One data item that is a member of a waveform data element or n-tuple. 
viewport- A defined area of the terminal screen (or display device). 


waveform data structure- A collection of data structures that reference the 
components of a waveform as represented for the SPD software. These com- 
ponents include waveform data array, data sampling interval, horizontal and verti- 
cal units strings, title and notes strings, and others. 


waveform array- The data array portion of the waveform data structure. 


waveform data element- A collection of one or more data values (tuples) that 
share the attribute of having been measured at one point in N-dimensional 
space and time. 


window, graphics- A defined area in the world coordinate system. 


window, signal processing- To multiply a waveform by some function to reduce 
the effects of leakage and time truncation errors. The SPD taper function 
provides the capability to window data by tapered as well as non-tapered window 
functions. 


world coordinate system- A coordinate system within a conceptual and infinite 
space. 


zone- to select a subsection of one or more dimensions of a waveform. 
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Waveform Storage 
Formats 


This appendix describes the SPD Waveform data structure using words and pic- 
tures. The formal definition of the structure and substructures are provided in 
Appendix C under the listing of the wav.h "C" header file. 


Waveform Measurement Data 


In signal processing applications (as well as others), data is usually sampled at 
regular intervals along some dimension (often, time is the dimension) and then 
stored in an array format. The terminology used in the SPD data structure is 
that each individual data item--that is, a single quantity at a single point in a 
dimension - is called a tuple. At each point in the dimension, more than one 
measurement may be taken. If measurements are taken, the collection of data 
taken at a single point is called an n-tuple. The data items in an n-tuple may be 
in the same units (e.g. volts) or they may be all different. In some applications, it 
is meaningful to collect data from a multi-dimensional space and keep it as- 
sociated in one data array. Each dimension represents a separate measurement 
axis. The length of all the dimensions may be the same (and in the same units) or 
they may all be different (and in different units). 


The number of dimensions, the number of samples in each dimension, and the 
number of tuples in each sample determine the size of the array needed to store 
the data. 


The SPD Waveform data structure permits you to store and describe multi- 
dimensional data arrays, each dimension is independent of the others (except to 
the extent the association means something to you). The only real constraint in 
this structure is that the tuple data (elements) are consistent among the dimen- 
sions where consistent means that the number of tuples in an element, the units 
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represented, and the data storage format (e.g. short integer or double precision 

float) is the same set for each n-tuple. For example, consider a three dimen- 

sional measurement space: X, Y, and Z. For any given value of X, Y, and Z, 

there is one element (n-tuple) of data. For any other value of X, Y, and Z, the 

structure of the clement data is the same. @ 


Most of the SPD signal processing functions assume that the data points along a 
given dimension are equally spaced. When needed, the distance is calculated 
using a supplied starting point, the sampling interval value, and the data sample 
number. (Nevertheless, you can use the SPD waveform data structure to store 
unequal interval data--simply use another tuple to record the sample time.) 


In some parts of this manual, including what follows, a dimension is described as 
representing time. That’s done simply for example and because it’s commonly 
so. Nothing in the SPD software assumes that te is involved. 


Associated Waveform Data 


Besides the actual measurement data, it’s often convenient to be able to carry 

along descriptive information about the data. The SPD Waveform data structure 

can store three groups of additional information: general, dimension, and tuple. 

Each SPD waveform can store the following general information: @ 


title a text string that describes the waveform data in words 
(optional); and 


notes a text string containing whatever you want it to (optional). 


For each dimension in the waveform, the following information is stored: 


a label a text string that describes the dimension in words (op- 
tional); 
a scale factor a number representing the sampling interval between ele- 


ments (measured in dimension units) (e.g. .001 for one 
millisecond between samples when the dimension units 
are in seconds); 


an offset factor a number representing the distance from the coordinate 
system origin to the first element (measured in dimension 
units) (e.g. .05 for .05 seconds since trigger); and 


units a text string that describes the measurement units (e.g. 
"Sec" for seconds) (optional). 
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The actual value represented by a dimension index can be computed by 


(act. value) = offset + (dimension index) * (scale factor) 


For each tuple in a data element, the following is stored: 


a type defines the data storage type (short, long, float, or 
double); 
a label a text string that describes the tuple (e.g. "signal 


strength") (optional); 
a scale factor a number which, when multiplied by the tuple data value, 


yields a value in tuple units (e.g. .001 if the values are in 
millivolts and the tuple units are volts); 


an offset factor a number that is an additive offset for the tuple data 
value (in tuple units); and 


units a text string that names the units in which the tuple 
values were measured (e.g. volts) (optional). 


Note that the actual value represented by a data value can be computed by 


(act. value) = offset + (data value) * (scale factor) 


There are other data stored in the SPD Waveform data structures that deal with 
the internal organization of the data but the items just described are all that are 
of interest to most users. If you care to further probe the data structure inter- 
nals, please read Appendix C and later sections of this appendix. 


Waveform Description Block 


The waveform description block is a data structure that describes the waveform. 
Multiple description blocks can be used to isolate subsections of the waveform 


for processing. In the event that more than one description block is used to 
describe a waveform or a portion of the waveform, there is a main description 


block that describes the waveform in its entirety. 


Figure B-1 shows a diagram of the data structures used to describe the 
waveform. The components of these data structures are described in the follow- 
ing sections. 


Signal Processing & Display B-3 


Waveform Storage Formats 


Previous Waveform Block 


rwnnotes 
Pweasize 


(NULL if First Block) 


STRING 


Array Location 


d flags 
d length 


ite 


d offset 


t flags 
t_type 


t_ offset 


7 anise - i 
& 


Fig. B-1. Waveform description block. 


Waveform Header Description Block 


A waveform header description block contains or points to information about a 


waveform. It consists of the following: 


W_prev 


B-4 


points to the previous description block, or is set to NIL 
("WAVEFORM *0") - the empty waveform pointer) if 


this is in the main description block. 
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w_subcnt 


w title 


w notes 


w_flags 


WwW asize 


w_elsize 


w_aptr 


w ndim 


w_dimptr 


w_ntuple 


w_tupleptr 


the number of subordinate waveform description blocks 
that directly point to this description block. 


points to a string describing the waveform. If no title has 
been assigned to the waveform, the string pointer con- 
tains NULL ("char *0" - the empty string pointer). 


points to a text string containing notes about the 
waveform. If there are no notes, the pointer contains 
NULL. 


a set of bit flags that indicate how memory has been allo- 
cated for various components of the waveform structure. 
They dictate whether that memory can be automatically 
freed in a free wf call or if the memory belongs to the 
user (hence cannot be automatically freed). 


In a main description block, this contains the total num- 
ber of elements in the array. In a subordinate description 
block, this location contains the total number of elements 
in the zoned or subordinate waveform. 


the number of bytes that are contained in an array ele- 
ment. | 


points to the location of the array data space. This 
pointer is of a type corresponding to the smallest storage 
unit (generally char*(BYTE)) for the host machine. The 
pointer should be cast to point to the actual data type 
when it’s used. 


the number of dimensions in the waveform. 


points to an array of data structures that describe the 
dimensions of the waveform. The length of this array is 
equal to the w_ndim. 


the number of tuples (vector components) that make up 
a single data element. 


points to an array of data structures that describe the 
tuples (components) of a waveform element. The length 
of the array is equal to w_ntuple. 


Waveform Dimension Description Block 


The Waveform Dimension Description block contains information about the 
dimensions of the array. 


d flags 
d_ length 


bit flags for handling special cases for dimensional data. 


the number of elements in the dimension of the 
waveform. 
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d_nextel the offset (in bytes) to the next element in the same 
dimension. 

d_label pointer to a text string. If there is no label, the pointer 
contains NULL. 

d_ scale multiplicative scale factor that determines the sampling 
interval or element spacing. | 

d_ offset the distance between the coordinate system origin and 
the coordinate system value of the first element in the 
dimension. 

d_units pointer to a text string that describes the units in which 


the dimension is measured. If no units string has been as- 
signed, the pointer contains NULL. 


Tuple Description 


The Tuple Description Block contains information about the observations 


sampled. 

t flags bit flags used for special case handling of tuple data. 

t_type type of data stored for this tuple (short, long, float, or 
double) 

t_index the offset (in bytes) from the first tuple in the element to 
this tuple. For example, if this is the first tuple, ¢ index 
== 0. If this is the second tuple, and the first is a short 
integer, t index == 

t_label pointer to a text string describing this tuple. If no label 
has been assigned, the pointer contains NULL. 

t_scale a multiplicative scale factor for data scaling. 

t_offset an additive scale factor. 

t_units points to the text string describing the units in which this 


tuple is measured. If no units string has been assigned, 


the pointer contains NULL. 


How Waveforms Are Stored In Memory 


The SPD Waveform data structure is organized such that the data can be parti- 
tioned into subsections (n-dimensional zones) so that these subsections can be 

processed individually. Figure B-2 shows a 4 x 2.x 3 space in which information 
about 3 quantities are contained at each point. The three quantities at each 


point are the tuples. 
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© Fig. B-2. Waveform structure and contiguous memory. 
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Let 


tuple 0 be a short integer (W_SHORT) = 2 bytes in length 
tuple 1 be a float (W_FLOAT) = 4 bytes in length 
tuple 2 be a double (W_ DOUBLE) = 8 bytes in length 


A waveform element consists of all the tuples, so for this example the element 
size is the sum of all the tuple sizes or: 


w_clsize = 2+ 4 + 8 = 14 bytes. 
For this example let: 


dim 0 = 4 elements — d length = 4 
dim 1 = 2 elements ~ d length = 2 
dim 2 = 3 elements — d length = 3 


The total number of elements in the waveform is the product of the elements in 
each division or: 


w size = 4x2x3 = 24 


to the next in d2, the distance is the size of the element or 14 bytes. Going from 
one element to the next in d/, the distance is the size of an element multiplied 
by the number of elements in d2, or 14x 3 = 42. Similarly in d/ the distance is 
14x3 = 84. 


The elements along any dimension are evenly spaced. Going from one element © 


Moving from one tuple to the next is determined by the size of each tuple. Ini- 
tially there is no offset to get to the first tuple (t0). tJ is located at a short dis- 
tance equal to the size of 10. So for tl, t_ index = size of (W_SHORT) = 2. The 
distance to #2 is similarly the size of t0 + the size of tJ, and for t2, t index = 2 + 
4 = 6. In this example dimension 2 has its elements adjacent followed by dimen- 
sion 1, then dimension 0. The default ordering of the elements in the waveform 
is such that the highest numbered dimension has its elements adjacent in 
memory. 


Constructing Subsections (Zones) of a Waveform 


Sometimes your waveform data contains data that is outside your region of inter- @ 
est--data gathered before or after the event of interest. The SPD waveform data 
structure provides a mechanism for zooming in on an area of interest. The pro- 

cedure is called zoning the waveform. Internally, this involves creating a subor- 

dinate waveform that is a subset of the original (possibly in multi-dimensional 

space if your original was multi-dimensional). Every waveform has a description 
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block. When partitioning a waveform into subordinate waveforms or zones, 
each subordinate waveform must also have a description block. The first ele- 
ment in this block is a pointer pointing to the main description block (or to the 
previous subsection description block if this is a subsection of a subsection). 
@ The remaining elements contain information about the subordinate waveform. 


Figure B-3 shows how to set up a two dimensional zone within a two dimen- 
sional waveform. 
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Fig. B-3. Zoning a waveform. 
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The subordinate descriptor block is set up to reflect the number of dimensions 
of the zoned data. The number of dimensions is less than or equal to the num- 
ber of dimensions in the original waveform. The dimension lengths of the zone 
equals the number of elements being included in that zone. The pointer to the 
array is set to point to the first element in the zone. Finally, the number of array 
elements is set to the total number of zoned elements. 


If only selected vector components in the waveform elements are to be used, the 
tuple data is adjusted in a similar manner. 


Figure B-4 shows this process for a one dimensional waveform with a vector con- 
taining two components. Notice that the original waveform descriptor block 
describes the entire waveform. The second block is set up to allow processing of 
the second component of the vector only. 
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Fig. B-4. Selecting a vector component. 
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Changing the Order of Array Evaluation 


Most SPD functions operate on the first dimension and the first tuple of a 
waveform only. Which dimension is first can be changed by the dim_reorder 
function. This function doesn’t move the memory elements around, but just ex- 

@ changes the order of the dimension structure. The ordering of the tuples can be 
redone by the tup_reorder function. It works similarly to dim_reorder. 


Addressing only one dimension of a multi-dimensional waveform, implies the in- 
dexes for the other dimensions are 0. In practice, if a multi-dimensional 
waveform exists, it will first be reduced to one dimension and one tuple by using 
combinations of dim_reorder, zone_dim, tup_reorder and possibly make_subwf. 
For example, consider a three dimensional waveform with dimensions X, Y, and 
Z. Let’s further assume that we want to look at the X axis data with Y = 3 (the 
fourth element), and Z = 2 (the third element). The following code fragment 
could be used. 


/*assume X is dimension 0 
. Y is dimension 1 


' Z is dimension 2 

*/ 

WAVEFORM *wave, “subwave; 
int order[1]; 


: Se aa 1, (long) 3, (long) 3, KEEP, &subwave); 
zone dim(subwave, 2, (long) 2, (long) 2, DELETE, &subwave); 
order|0] = 0; 
dim_reorder(subwave, 1, order, DELETE, &subwave); 


This code fragment first selects element 3 from the Y dimension, then element 2 
from the Z dimension by calling zone-dim twice. At this point subwave is 3 
dimensional with the Y and Z dimensions each having only one element. Final- 
ly, dim_reorder is used to extract the X dimension. This last step is not neces- 
sary in this example, because the SPD functions only look at the first dimension. 
If you want to look at some other dimension, this step would be necessary to 
make that dimension, dimension 0. 
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Appendix C 
SPD Header Files 


The following section lists the SPD C and QuickBASIC include files. The C (/) 
files are listed together as are the QuickBASIC (.br) files: 


acq.h definitions for use with the acquisition functions. 
acq.bi 

eq _fir.h defines the specifications for and type of filter to be 
eqfir.bi designed 

machdep.h contains machine dependent definitions 

sp.h contains common signal processing definitions 

sp.bi 

spd.h contains general definitions used throughout SPD 
spd.bi 

tekgr.h contains definitions for SPD Graphic Display Functions 
teker.bi 

tekspd.h combines header files (except for eq_fir.h) 

teksd.bi 

wav.h contains definitions for waveform data structures used 
wav.bi throughout SPD 
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vc 
* 
ve 
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¥c 


* Version 1.0 September, 


1988 


* Copyright (c) Tektronix 1988 


vc 


Ye Ye Ye He He ve Ye He He Ye Ye He He Fe Fe He He He Ye He Ye He He Fe He He He Ye He He Ye He Fe Fe Fe He He Fe He Ye Ye Fe He Fe Ye He We Fe Ve Fe Ye Ye He Ye Ye He He He Ye Ye Fe He Me Ye Ye Fe Ye Ye Ye / 
/* Definition of POLL mode and Waveform sources */ 


acq.h 


/* waveform sources for the 11k family */ 


/* waveform sources for the 2220/2221 */ 


Infinite timeout (disabled) 


Timeout 
Timeout 
Timeout 
Timeout 
Timeout 
Timeout 
Timeout 
Timeout 
Timeout 
Timeout 
Timeout 
Timeout 
Timeout 


of 
of 
of 
of 
of 
of 
of 
of 
of 
of 
ot 
of 
of 


for the 5223 */ 


10 us (ideal) 
30 us (ideal) 
100 us (ideal) 
300 us (ideal) 
1 ms (ideal) 

3 ms (ideal) 
10 ms (ideal) 
30 ms (ideal) 
100 ms (ideal) 
300 ms (ideal) 
1s (ideal) 

3 s (ideal) 

10 s (ideal) 


#define POLL ~] 
#define CH1 0 
#define CH2 1 
#define REF1 ied 
#define REF2 3 
#define REF3 4 
#define REF4 5 
#define REF4 2220 2 
#define ADD 6 
#define MULT 4 
#define CH1D 8 
#define CH2D fe) 
#define ADDD 10 
#define MULTD 11 
#define TRACE i 
#define STO 2 
#define ACQ 1 
/* Acquisition modes for the 7912 */ 
#define ATC 1 
#define SA 2 
#define EDGE 3 
/* Acquisition sources 
#define L 0 
#define Ll 1 
#define L2 2 
#define R 3 
#define R1 4 
#define R2 a 
/* Timeout values and meanings */ 
#define TNONE 0 /* 
#define T10us L /* 
#define T30us Z /* 
#define T100us a /* 
#define T300us 4 /* 
#define Tims 5 /* 
#define T3ms 6 /* 
#define T10ms 7 {* 
#define T30ms 8 /* 
#define T100ms 9 6 6/* 
#define T300ms 10 /* 
#define Tls li = /* 
#define T3s ewe /* 
#define T10s 13 /* 
C-2 
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SPD Header Files 


acq.h 
#define T30s 14 /* Timeout of 30 s (ideal) wf 
#define T100s ees /* Timeout of 100 s (ideal) w/ 
#define T300s 16 /* Timeout of 300 s (ideal) */ 
#define T1000s 17 /* Timeout of 1000 s (maximum) w/ 
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ve 
¥ 
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eq fir.h 


ve 
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Version 1.0, May 22, 1985 


* 
ve 
* Copyright (c) Tektronix 1985 
bid 
vc 


released 05/22/85 


* 


vc 


We ate ae ve ae aie ve aie ae ie aie ae ve ae ae ae ae ae ae aie ae ae ae ae eae a eae eae ee aie He ee ae ae eae ae ee ae ee ae ae ae ve aie aoe ae eae He He de ve He ae Ye He ae ie // 


/* 


* This file contains the code for the spd include file "eq fir.h" 


ie 
#define MAXBANDS 
/* 


10 


* Filter type to be designed 


wy 
#define PASSSTOP 
#define DIFF 
#define HILBERT 
#define FUSER 


/* 


WNr Oo 


/* max number of bands in filter */ 


* Filter band structure definition 


ye / 

struct fband { 
double blower; 
double bupper; 
double bmag; 
double bweht; 

yy 


/* 
/* 
/* 
/* 


typedef struct fband FBAND; 


/* 


frequency of lower edge of band my 
frequency of upper edge of band tf 
band mag (1, 0) or slope if DIFF “/ 
weighting for band w/ 


* Filter specification definition 


mf 

struct fspec { 
short flen; 
short ftype; 
short nbands; 
FBAND band [MAXBANDS] ; 

Hf 

typedef struct fspec FSPEC; 


/* 
/* 
/* 
/* 


length of filter ve / 
filter type PASSSTOP, DIFF, HILBERT */ 
number of bands in filter vf 
filter band definitions w/ 


ERRORTYPE eq_fir(FSPEC*, int ,WAVEFORM* , WAVEFORM* , double*) ; 
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machdep.h 
DARIO CIO CO OCI OIO OOO RIOR IIT IIIT I IIT RI Ter Re rete detente dete tere rere ie yer 
big x 
m machdep.h - 
ve ¥ 
Ye to He He ve He ve Xe Te ve He He Fe He Xe He Xe He ve He He Fe He Xe Fe Fe ve ve He Fe He He He He He Fe te Fe Fe He He Ye Fe Fe Fe te Fe te He Fe Fe tc He Xe ¥e Fe He Xe Fe Fe Fe Fe Fe te Fe Fe Fe Fe ye 4 
¥ ve 
* Version 3.0, Jan 12, 1988 * 
* Copyright (c) Tektronix 1985, 1987, 1988 
* ve 


Ae Fe Fe ve ve ae He He He He Ve Fe Ye He Ye He Ye He He ve He ae He ae He Ae ae He He de ve ve ve He He He He Ye He ae He He Ae Ye Ye ve ve ae He He He Yee ie Hee He de He Me He Ye Ye ve ae He ee Ie / 
/ 40 Fe Fe He Hee He Ye He Ve ve He Fe ve Ye ve He Ye He He ve He Ye He ve He Ye He Ye ve He He He He He He He He Ye He He He He He He Ye He Ye ve He Ye He Ye Ye He Ye He Ye He He Fe Ye Te ¥e He Ye Ye He Fe 


ve ve 
* machdep.h -- contains the machine-dependent definitions is 
* Several conditional compilation directives exist in the spd library.” 
* The following lists the names of each and their function: : 
* DOS -- Should be defined when running under MS-DOS. 
ve v 
He ae ve at ae aie aie a ae ae ie aie ae ae aie arr eae ae ate aie aie vie ir aie aie aie aie ae eae aie aie eve vie Yc oie aie ae vie ai ie air ae air aie ae de ae ae aire ae ae ae ae ae ie ie aie aie de ae ae Ue ae ae / 
typedef long INDEX; 
# define NIL OL /* system nullpointer, must */ 

/* not be redefined to any a 

/* other constant at 3 
# define MAXBYTES Ox7FFFFFFFL 
# define lint /* removes RCSid's a 
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sp.h 

/ Yee Fe se Fe Fete de te Fe He ve ve ve He ve Ye He ve He ve ve te He ve ve Ye ve He ve ve ve ae Ye eve Ye Ye He He Fe He He He He He Ye He He He Fe Me He He He Fe Ae He He Fe He He He He He He He Fe Ye 
big Ye 
¥ sp.h ” 
vc * 
ve ve ve Ye He Ye He ve Fe He He He He He He He Ve Ve Ve He He He He 9 Ve Ye He He Fe Ye Ve Fe He He ve Fe He He He He Te ve He He He He He Fe Fe Ye Fe Fe ve Fe Fe Fe Ye Fe ge ve Fe ve ve Fe ¥e Fe Fe ve He ve 
* ve 
* Version 1.0, May 17, 1985 - 
* Copyright (c) Tektronix 1985 " 
* * 
* released 05/17/85 ™ 


Ye ae ae ve ate ae aie ae ae ae ae ve ae ae ae ae ae eae aie ae ie ae ae ae de de aie ae ae ae ae ae de eae ve ae ae ve ae ae ae ae ae ae ae ae ve ae de He ae Ye ie de aie ae ae ee ee He Ye He Yee He / 
/ ve 
* This file contains common definitions used in signal processing 
* routines. 
mf 
/* 
* general mathematical constants 
vc / 
#ifndef PI 


#define PI 3.14159265358979323846 
#endif 


#define EXP 2.71828182845904523536 
#define SQRT2 1.41421356237309504880 
#define HALFSQRT2 70710678118654752440 


/* 
* Polar and rectangular coordinate definitions 
ae J 

#define RAD 0 

#define GRAD i 

‘#define DEGREE 2 


typedef int UNIT; 


End-of-Array algorithm selection codes. 


7, 
+ 


EA REPEAT -- Repeat array ending value. All elements before the 
array start are equal in value to the first element Arr[0], and 
all elements after the array end are equal in value to the 

last element Arr[N-1], where N is the length of the array. 


EA BOUNCE -- "Bounce" off array ends to pick replacement value. 
Arr[(-i] is replaced with Arr[{t+i], and Arr[N-1+i] is replaced with 
Arr[(N-1-i], where 0 <i <N, 


+ 4+ 4+ + % $+ + + 4+ 4% 4 


EA_INVERT -- “Bounce and invert". Same as EA BOUNCE, except the 
Sign of the selected element is changed. Thus, Arr[-i] is replaced 
with -Arr[(ti], etc. 


* 


EA WRAP -- “Wrap” around from the end back to the start and wrap 
around from the start to the end. This makes the array appear 
“circular”, as if the array was repeated over and over with 

the data values in the same order for each repetition. In 

this case, Arr[-i] is replaced with Arr[N-i], and Arr[N-1+ti] 

is replaced with Arr[i-1], where 0 < i <=N. 


+ 4 t+ 4+ + $+ 4 4 HF SF 


EA_ZERO -- An array element with subscript that is not in the 
array bounds is set to zero. So Arr{iJ] = 0 if i< 0 or i >=N. 


~/ 
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sp.h 
#define EA REPEAT 
#define EA BOUNCE 
#define | EA INVERT 


#tdefine EA WRAP 
#define EA_ZERO 


5 ve 


-wWwNnNr O 


/* Windowing function selection codes 


* 
* RECTANGULAR =0.,0 n= 0 to num 
* 
* TRIANGULAR =n/(num/2) n= 0 to num/2 
sd =num-n/ (num/2) n= num/2 to num-1 
ve 
* HANNING =,5*(1-cos(2*PI*n/num) ) n= 0 to num-1 
¥c 
* HAMMING =.54-.46*cos(2*PI*n/num) n= 0 to num-1l 
* 
* BLACKMAN =,42- .5*cos(2*PI*n/num)+ n= 0 to num-l 
* 08*cos(4*PI*n/num) 
¥c 
* FLATTOP =,36-.49*cos(2*PI*n/N) + n= 0 to num-1l 
sd .14*cos(4*PI*n/N) - 
* .01*cos(6*PI*n/N) n= 0 to N-l 
+ 
ve 
where: num = number of elements in array, if even; 
* number of elements minus one, if odd 
” n = index of array element 
vr 

*/ 

#define RECTANGULAR 0 

#define TRIANGULAR 1 

#define HANNING 3 

#define HAMMING 3 

#define BLACKMAN 4 

#define FLATTOP 5 


/* Square wave transitions types 


* 


RAMP 


SIN2 


+ * 4+ %* 4+ 4% 4+ 4% + + HH 4 4 FS F 


+ 
a 


#define 
#define 
#define 


transition edge is a sloped line: 
rising edge -- slope * time 
falling edge-- amplitude + slope * time 


(a step wave can also be formed using 0 rise time and fall time) 


EXPON -~*% NOT IMPLEMENTED **% - 


--transition edge is the integral of sin(x)**2: 


rising edge -- integral of (2 * amplitude / pi) * sin(x)**2 
from x = 0 to x = theta, as theta ranges from 
0 to pi 


falling edge-- integral of (2 * amplitude / pi) * sin(x)**2 
from x = 0 to x = theta, as theta ranges from 


pi to 0 
RAMP 1 
EXPON 0 
SIN2 2 


typedef int TRANSTYPE; 
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jx 
* Symmetry conditions for convolution used in the differentiation 
¥ 
* NOSYM este -no symmetry involved 
ve 
* ODDSYM <-- odd symmetry; h[n]) = -h[N-1-n]) © 
¥ 
_— — even symmetry; h[{n) = h[N-1-n] 
* 


#define NOSYM 0 

#define ODDSYM 1 

#define EVENSYM 2 

/* 
* Type of interpolator to use for simple 1 point interpolation 
* Two types are available. Sinc interpolation, and Lagrange 
* interpolation 


* / 
#define SINC 0 
#define LAGRANGE 1 
/* 


* Flag to indicate SUM or AVE in sumave. SUM will produce a sun, 
* and AVE will average. 
me 

#define SUM 0 

#define AVE 1 


/* 

* Flag to indicate direction of search for waveform crossing. 
* Used in the cross routine. 

al 


#define LEFT 0 
#define RIGHT 1 


+ 


The following definitions are used to choose an interpolation 
filter type in the routine w_interp.c. In addition to this, 
w_interp.c needs SINC to be defined. This has been previously done 
* for pt_interp.c 


+ + 


=? 

#define LINEAR 1 

#define USER_FILT 2 

/* 

* Flag to indicate which kind of analysis of histogram to use in 
* pls_ hist 

ae 


#define MODE 0 
#define MEAN 1 
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spd.h 
J Bee He He He Fe He He He Fe Ke Fe He He He He He HH HHH IH HH HI HHH KKH IKI KIKI KKK KI KK KK IK IK eK Ik I 
* * 
* spd.h ” 
* 5 


Fe He He Fe He He He He He He Fe He Fe Fe He He He He He Ye He ¥e He He Fe He He He He He He He He He He Fe We Fe He He He He He Fe He Fe Fe He He Fe He He He Fe Fe He He Fe Fe He Fe Fe He He He He He Fe He Kc 
* 


*Version 2.2, Sept 6, 1988 
*Copyright (c) Tektronix 1985, 1988 
* 


+ + + & 


He He Fe He He He He He He He He He He He He He He He He He He He He He He He He HK HK HK HHH HK IK HH HH HK HK HH KH KK He HK He He He He He He He He He He HH He He HK / 
/* 

* This file contains the general definitions used throughout SPD. 

ad 


/* 
* General System Definitions 
"yf 

#define VERSION "SPD V2.2" 


#define TRUE 1 
#define FALSE 0 


typedef int BOOL ; 
/* 

* Error handling hook 
iat J 


#define ON 1 


i : 
* Min and Max numeric values for the various number types 


a 


#define MINSHORT -32768 

#define MAXSHORT 32767 

#define MINLONG ~2147483647L 

#define MAXLONG 2147483647L 

#define MINFLOAT -1.701411733192644270e38 
#define MAXFLOAT 1.701411733192644270e38 
/* 


* Mask definition for random number generators 

* Defined so that generators will work when a long int type 
is 

* representable by at least 32 bits 

a 


#define |§RANDMASK OX7FFFFFFFL 
/* 
* Error handling definitions 
=; 
typedef int | ERRORTYPE; 
/* 


* Error code definitions 
a 
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#define NOERROR 0 
#define WARN 1 
#define FATAL Z 
#define CRASH 3 
#define |GRAPH_ERR 4 
#tdefine PARAM ERR 5 
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tekgr.h 
[Fe Fe te Ye te He ve te He ve He He ve He te He vee Ye vee ve He He He He He te ae He ve He de He de He He ve He Fe He de ve He ae ve He Fe He Ye He Ye He He Ye He Ye ve He Tee He He He Ye He Ye Ye Fe 
vr ve 
a tekgr.h i 
vc vc 
¥e Ye Fe Fe Ye Fe Ye He Ye He He ve He Fe ve Ye ve ve Ye ae He Ye eve ve He ¥e He Ye He He Ye Fe He ¥e Fe He He ve Ye He He He He Fe ve He ve ve ve He He ve ve He ve ve ve Ye Ye Fe Fe Fe Fe Fe Fe Fe Fe Fe Fe 
ve ve 
*Version 2.0 September, 1988 s 
*Copyright (c) Tektronix 1985, 1988 a 


ve ve 
Ye Fe ve ve He ve ve He ve He Ae Fe He de He Te ate He ve ae He ve He Ye ae Ye Fe He He He Fe He Ye ve Ye Ye He Ye He Ye He Ye Fe He He He Ye He He Ye He Ye He He Ye He Ye ve He Fe Fe He Ye He Ye He He Ye Fe / 
/* 
tekgr.h -- include file for Signal Processing Data 

Graphing Function Package 
% f 
/* these are the default VDI colors */ 
#define BLACK 
#define WHITE 
#define RED 
#define GREEN 
#define BLUE 
#define YELLOW 
#define CYAN 
#define MAGENTA 


/* these define the line styles */ 


NOWnfWNFr O 


#define DEJAG a | 
#define INTRP =Z 
#define WVFRM ~2 


#define INTRP_ DEJAG -3 
#define WVFRM DEJAG -3 


#define SOLID 1 

#define LONG DASH Z 

#define DOTTED 3 

#define DASH_DOTTED 4 

#define MED_DASHED 5 

#define DASH_2DOTS 6 

#define SHORT_DASH 7 

/* there are 6 available polymarker types */ 
#define DOT 1 

#define CROSS 2 

#define STAR 3 

#define SQUARE & 

#define X_MRKR 5 

#define DIAMOND 6 

/* an axis can be one of two types */ 
#define | LIN_AXIS 0 

#define LOG_AXIS 1 


/* text alignment options */ 
#define LEFT_JUST 0 
#define CENTER JUST 1 
#define RIGHT_JUST 2 
#define BOTTOM JUST 0 


#define TOP_JUST 2 
/* define options for setting graph type and text origin */ 
#define DISPLAY GRAPH 0 


#define | TEXT ONLY 1 
#define | XY_VWPORT_RELATIVE 0 
#define | XY DISPLAY RELATIVE 1 
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/* define grid types */ 

#define NO_GRID 0 
#define SOLID_GRID 1 
#define DOTTED_GRID 2 


/* define options for text alignment */ 


#define UPPER_LEFT i 
#define UPPER_RIGHT 2 
#define LOWER_LEFT 3 
#define LOWER_RIGHT 4 
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/ Fe Fe Ye Te Ye He Ye ve He Ye te He Ye He He He Ye He He ve He He Ye He Ye He He He ve He He Ye He ve He He Ye He Ye He ve He He ve He Yee He Ye He Ye Ae Ye ae He ve ee He He He ¥e ee ae He Fe He Fe 
bid ¥ 
m tekspd.h a 
* v 
Fe Fe Ye Fe ae ae He ae ae ae ve ae ie ae ae ae He We Fe Ye ie ae ae ee ae ve ae ate ae ete ve te ie te oe ee ae He He He He He He Ye He Fe Fe Fe Ye Te Ye Fe Fe He Ye Ye He Ye Fe ae He Ye Fe Ne ae Ye Ie 


vc ve 


* Version 2.1, September, 1988 * 
* Copyright (c) Tektronix 1985, 1987, 1988 * 
* vc 


Ye ve de ie ve te aie ie ve He ve ae ve He ve ee vee ve He ee ae ae de ae ae vee vee ie He ate ee ae ae Yee ve de ee ae ae ae ae eee Hee dee Fe He Ye ae Ye eve He ve Te Ye Te Ye / 


#define DOS 
#define MSC 
#define BIGMEM 
#include "wav.h" 
#include "spd.h" 


#include ' 


‘sp.h" 


#include "tekgr.h" 
#ifndef FILE 
#include <stdio.h> 


#endif 


/* SPD signal processing library function prototypes */ 


ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 


ERRORTYPE 
ERRORTYPE 
ERRORTY PE 


ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTYPE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 


afile to _wf(char*,WAVEFORM** ) ; 

arrl_ to _wf(void *,long, int,WAVEFORM** ) ; 

arr_to wf(void *,int, long*,int, int* ,WAVEFORM** ) ; 

clr_err(int); 

convolve (WAVEFORM* , WAVEFORM”, long, int, int ,WAVEFORM* ) ; 

copy_wf (WAVEFORM* , WAVEFORM** ) ; 

cpx_add(WAVEFORM* , WAVEFORM* , WAVEFORM* , WAVEFORM* , WAVEFORM” , 
WAVEFORM* ) ; 

cpx_div(WAVEFORM* , WAVEFORM* , WAVEFORM* , WAVEFORM* , WAVEFORM* , 
WAVEFORM* ) ; 

cpx_mult (WAVEFORM* , WAVEFORM* , WAVEFORM* , WAVEFORM* , WAVEFORM” , 
WAVEFORM* ) ; 

cpx_sub(WAVEFORM* , WAVEFORM* , WAVEFORM* , WAVEFORM* , WAVEFORM* , 
WAVEFORM® ) ; 

createl wf(long, int,WAVEFORM** ) ; 

create wf(int, long*, int, int* ,WAVEFORM** ) ; 

cross (WAVEFORM* , long,int,double,int,int,int,double”*) ; 

df to wf(char*,int,int,int,int, int, WAVEFORM**) ; 

diff(WAVEFORM* , int, int ,WAVEFORM* ) ; 

dim_reorder (WAVEFORM*, int, int*, int , WAVEFORM** ) ; 

disabl_ fpe(void) ; 

enabl_ fpe(int); 

err_file(FILE*) ; 

fconv (WAVEFORM* , WAVEFORM* , WAVEFORM* ) ; 

fcorr (WAVEFORM* , WAVEFORM* , WAVEFORM* ) ; 

££t (WAVEFORM* , WAVEFORM* , WAVEFORM* , WAVEFORM* ) ; 

file _to_wf(char* ,WAVEFORM** ) ; 


void fr_array(void *); 
void fr_block(void*) 
void fr_string(char*) ; 


ERRORTYPE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
ERRORTY PE 
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free wf (WAVEFORM*) ; 
ifft (WAVEFORM* , WAVEFORM* , WAVEFORM* , WAVEFORM*® ) ; 
initbin(long) ; 

initgaus(long) ; 

initunif(long); 

integrate (WAVEFORM*, int ,WAVEFORM* ) ; 

irfft (WAVEFORM* , WAVEFORM* , WAVEFORM® ) ; 

make_subwf (WAVEFORM* , WAVEFORM** ) ; 

make_target (WAVEFORM* , WAVEFORM** ) ; 
meanstd(WAVEFORM* , double* , double* , double*,double*) ; 
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ERRORTY PE 
void* 
void* 
char* 
ERRORTYPE 
ERRORTYPE 


ERRORTYPE 
ERRORTYPE 
ERRORTY PE 


ERRORTY PE 
ERRORTYPE 


ERRORTYPE 
ERRORTYPE 


ERRORTY PE 
ERRORTYPE 


ERRORTYPE 
ERRORTYPE 


ERRORTYPE 


ERRORTYPE 
int. 
double 
double 
ERRORTYPE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTYPE 
ERRORTYPE 
ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTYPE 
ERRORTY PE 
ERRORTYPE 


long 
long 
long 
ERRORTYPE 
ERROR YPE 
ERRORTYPE 
ERRORTYPE 
ERRORTYPE 


ERRORTYPE 
ERRORTY PE 
ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
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minmax (WAVEFORM* , double* , double*, long*, long*) ; 


mk_array(long,unsigned int); 
mk _block(unsigned int); 
mk_string(unsigned int); 


pls_amp(WAVEFORM*, long, long, long,int,int,double*,double*) ; 
pls_calc (WAVEFORM, long, long,int,double,double,int,int, 


double*,double*) ; 


pls_dutyf(WAVEFORM*, long, long, int,int,double*) ; 
pls_edge(WAVEFORM*, long, long,int,int,int, long*, long*, long”) ; 
pls ftime(WAVEFORM*, long,long,int,double,double,int,int, 


double*,double*); 


pls_hist(WAVEFORM*, long, long, int,int,double*,double*) ; 
pls_meas (WAVEFORM*, long, long,int,int,int,int, 


double*,double*); 


pls_negpk (WAVEFORM*, long, long ,double*, double*) ; 
pls_pamp(WAVEFORM*, long, long,int,int,int,int, 


double* ,double*) ; 


pls_period(WAVEFORM*, long, long, int, int,double*) ; 
pls_pkfind(WAVEFORM*, long, long, int,double,double,int, 


double* ,double*) ; 


pls_pospk (WAVEFORM* , long, long, double* ,double*) ; 
pls_rtime(WAVEFORM* , long, long,int,double,double,int, 


int, double*,double*); 


polar (WAVEFORM* , WAVEFORM* , int, int, double ,WAVEFORM* , 


WAVEFORM* ) ; 


pt_interp(WAVEFORM*, int,double,int,int,double™*) ; 


randb(double); 
randg(double,double) ; 
randu(void); 


read_num(WAVEFORM*, int, long*,double*) ; 
rectang (WAVEFORM* , WAVEFORM” , int , double ,WAVEFORM* , WAVEFORM* ) ; 


rfft (WAVEFORM* , WAVEFORM* , WAVEFORM* ) ; 
rpt_count(int, long, char*) ; 
rpt_err(int,char*) ; 

set_err(char*) ; 

shutdown (void) ; 


sin2(double,double, double, double ,WAVEFORM* ) ; 

sinc (double, double, double, double ,WAVEFORM* ) ; 

sinemeas (WAVEFORM* , int ,double,int,double*,double*, double”); 
sinewave (double, double,double, double, WAVEFORM* ) ; 

Squarewave (double, double,double,double,double,int,double, 


int , double , WAVEFORM* ); 

state b(void); 

State g(void); 

state_u(void); 

sumave (WAVEFORM* , int, int , WAVEFORM* ) ; 


taper (WAVEFORM* , int , double , WAVEFORM* ) ; 


titlLept (WAVEFORM** , char*, int); 


tupreorder (WAVEFORM** int, int*, int ,WAVEFORM** ) ; 


validcheck (WAVEFORM* ) ; 


we_add(WAVEFORM* , double , WAVEFORM* ) ; 

we_div(WAVEFORM* , double , WAVEFORM* ) ; 

wc_max(WAVEFORM* , double , WAVEFORM* ) ; 

we_min(WAVEFORM* , double , WAVEFORM* ) ; 

we_mult (WAVEFORM* , double , WAVEFORM* ) ; 
wc_ sub (WAVEFORM* , double , WAVEFORM* ) ; 

wf_dlabel(char*,int, int ,WAVEFORM*) ; 

wf_dunits(char*, int, int ,WAVEFORM* ) ; 

wf notes(char*, int ,WAVEFORM* ) ; 

wf _title(char*, int ,WAVEFORM* ) ; 
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ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 


SPD Header Files 
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wf tlabel(char*,int,int,WAVEFORM*) ; 

wf _to_afile(WAVEFORM*, int, char*) ; 
wf_to_arr(WAVEFORM* ,void **); 

wf _to_file(WAVEFORM*, char*) ; 

wf tunits(char*,int, int, WAVEFORM*) ; 

write _num(double, int, long* ,WAVEFORM* ) ; 
w_add(WAVEFORM* , WAVEFORM* , WAVEFORM* ) ; 

w_decimate (WAVEFORM*, int, long ,WAVEFORM*) ; 
w_div(WAVEFORM* , WAVEFORM* , WAVEFORM* ) ; 
w_exp(WAVEFORM* , double , WAVEFORM* ) ; 
w_interp(WAVEFORM*,int,int,int,double*, int ,WAVEFORM*) ; 
w_log (WAVEFORM* , double , WAVEFORM* ) ; 

w_max (WAVEFORM* , WAVEFORM* , WAVEFORM* ) ; 
w_min(WAVEFORM* , WAVEFORM* , WAVEFORM* ) ; 

w_mult (WAVEFORM* , WAVEFORM” , WAVEFORM* ) ; 

w_power (WAVEFORM* , double , WAVEFORM* ) ; 

w_sqrt (WAVEFORM* , WAVEFORM* ) ; 

w_sub (WAVEFORM* , WAVEFORM* , WAVEFORM* ) ; 
zone_dim(WAVEFORM*, int, long, long, int ,WAVEFORM** ) ; 


/* SPD graphics library function prototypes */ 


ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTYPE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTY PE 
ERRORTYPE 
ERRORTYPE 
ERRORTY PE 
ERRORTYPE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
ERRORTY PE 
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gr_addev(int,int,int,int,int); 
gr_addmk(int,int,int,int,int); 
gr_autoscale(int) ; 
gr_autotics(int); 
gr_axclr(int) ; 
gr_axes(int,int); 
gr_back(int,int,int); 
gxr_box(int); 

gr_clear(void) ; 
gr_close(void) ; 
gr_curv(int,int,int,int,int); 
gr_defa(int, double, double) ; 
gr_defd(int, long, double*) ; 
gr_deff(int, long, float*); 
gr_defw(int, WAVEFORM* ) ; 
gr_dev(char*) ; 
gxr_dsply(void); 
gxr_frame(int); 
gr_grid(int,int,int,int); 
gxr_han(int*); 
gr_indent(int, int); 
gr_init(void) ; 

gr_legnd(int, int); 
gr_lgenst(int,char*) ; 
gr_mrkr(int,int,int,int,int); 
gr_owo(int); 

gr_pause(void) ; 
gr_reset(void) ; 
gr_size(double, double, double, double) ; 
gr_stitl(char*, int) ; 
gr_text(int,char*,int,int,int,int,int,int,int) ; 
gr_title(char*, int); 

gr_txorg (int); 

gr_type(int); 

gr_uncurv(int) ; 
gr_undef(int); 
gr_update(void) ; 
gr_vwpt(int,int,int,int); 
gr_xlabl(char™, int); 
gr_xrang(double, double) ; 
gr_xtics(double, double); 
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ERRORTYPE 
ERRORTYPE 
ERRORTYPE 


gr_ylabl(char*, int); 
gr_yrang (double, double) ; 
gxr_ytics(double, double) ; 


/* SPD acquisition library function prototypes */ 


ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
ERRORTY PE 
ERRORTYPE 
ERRORTYPE 
ERRORTYPE 
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get2220(WAVEFORM** , short, short,short,short) ; 

get2230 (WAVEFORM** , short, short,short,short, short); 
get2430(WAVEFORM** ,short,short,short,short,short) ; 

get7D20 (WAVEFORM** , short, short,short,short,short) ; 

get5223 (WAVEFORM** ,short,short,short,short,short); 
getl1K(WAVEFORM** ,short,short,short,short,short,short) ; 
get7912(WAVEFORM** , short, short,short,short,short,short) ; 
get7854 (WAVEFORM** , short, short,short,short,short); 
getRTD710(WAVEFORM**, short, short,short,short,short,short); 
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* ¥ 
sd wav .h © 
* ¥ 
Fe Fe Fe ve He He ie He He aie ie de He ae He Ye He He Ye He ve ve He Ye ve He He He He He He Ye Ye Fe He ie He He Fe He ve He He ve He He Fe He He Fe te He te He He Fe He He He He He He He He He ve He Fe ¥e Ae 
* ¥ 
* Version 2.1, September 26, 1988 ™ 
* Copyright (c) Tektronix 1985, 1987, 1988 a 
* ¥ 


Fe ve Fe ve ve ve He ve Fe ve He He ve te He He eve ae He He ve ve He He ie He Ye Fe Ye He He Ye ve He He ve Ye Ye He He He Ye de He ie ve Ye He He Ye Ye Ye He He He Ye Te He He Ye He He He Fe Te He He Ye He / 
#include "machdep.h" 
/* 

* This file contains the definitions of the waveform data structures 

* used throughout the system. 


/ 

typedef unsigned char BYTE; 
typedef char STR_HDR; 
/* 


* Dimensional description data structure. This structure describes 
* one dimension of a waveform. 


at J 


struct w_dim { 
short d_flags; /* bit flags for special case handling */ 
long d_length; /* number of elements in dimension */ 
long d_nextel; /* inc (bytes) to next element in dim */ 
char *d label; /* pointer to string describing dim */ 
double d_ scale; /* multiplication scale factor for dim */ 
double d offset; /* axis offset for dimension space */ 
char ‘*d_units; /* pointer to dimensional units info */ 

j 

typedef struct w_dim W_DIM; 


[x 
* Tuple description data structure. This structure describes one 
* element in a set of ordered data. 

«f 
struct w_tuple { 
short t_flags; /* bit flags for special case handling */ 
short t_type; /* element type: short, long, float, double */ 
long t_index; /* offset (bytes) from lst ordered element 
to this element */ 
char *t label; /* pointer describing this element */ 
double t_scale; /* multiplication scale factor for element */ 
double t_offset; /* additive scale factor for element */ 
char *t units; /* pointer to element units infomation */ 


}; 
typedef struct w_tuple W_TUPLE; 
/* 
* Waveform description block definition 
*f 
struct waveform { 
struct waveform *w_prev; /* ptr to previous header definition */ 
short w_subcnt; /* number of subsequent wf's that 
point*/ 
/* to this as the previous */ 
char *w title; /* ptr to waveform label (title) */ 
char *w notes; /* ptr to waveform notes area */ 
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short w flags; /* bit flags for special case handling */ 
long w_asize; /* total number of elements in array */ 
long w_elsize; /* size of data element (in bytes) */ 
BYTE *w aptr; /* pointer to array */ 
short w_ndim; /* number of dimensions in waveform */ 
W_DIM *w dimptr; /* pointer to dimensional data */ 
short w_ntuple; /* number of elements in ordered data */ 
W_TUPLE *w tupleptr;/* pointer to tuple data */ 


}; 
typedef struct waveform WAVEFORM; 


/* 

* Defines for standard tuple labels 

iad 

#define DIGLEVELS "Dig Levels" 

#define VOLTS "Volts" 

/* 
* Defines for keeping/deleting-the-source-wf flagword 
* / 

#define KEEP 0 

#define DELETE 1 

/* 
* Defines for copying/linking to waveform strings 
wt J 

#define LINK 0 

#define COPY 1 


ee ® 


* Defines for maximun number of dimensions and tuples 
i 3 

#define MAXDIMS 10 

#define MAXTUPS 256 


/* 
* Defines for w_tuple->t_type 
af j 

#define W_UNDEF 

##define W_SHOR 

#define W_LONG 

#define W_FLOAT 

#define W_ DOUBLE 


~-WNHre O 


/* 

* Defines for d_flags in the Waveform Dimension Structure 

“s 
#define WFD_LABEL 1 /* dimension label releasable in normal manner*/ 
#define WFD_UNITS 2 /* dimension units releasable in normal manner*/ 


/* 
* Defines for t_flags in the Waveform Tuple Structure 
“S 
#define WFT_LABEL 1 /* tuple label releasable in normal manner */ @ 
#define WFT_UNITS 2 /* tuple units releasable in normal manner */ 
/* 
* Defines for w_flags in the Waveform Description Block 
my 


#define WF_WDB 1 /* waveform description block allocated on heap 
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a 
#define WF_ARR 2 /* array releasable in normal manner */ 
#define WF_DIM 4 /* W_DIMs array allocated with WDB */ 


#define WF_TUP 8 /* W_TUPLEs array allocated with WDB */ 
#define WF_TITLE 16 /* title releasable in a normal manner */ 
#define WF_NOTES 32 /* notes releasable in a normal manner */ 
#define WF_XY 64 /* first two tuples are plotted as XY plot */ 


[ ¥e Fe te Ye ae He Ye Ye ve ve Ye ve He He ve Ye ve Fe Ye Ye He He ve ve ee ve He ve ve ie He ve ve de He vee He eae He ve ve He He Ye Fe He He ve aie He He ve He He He Fe ie He He ee He Ye Fe Ie ae 
ve 
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% 
ve 
¥ where: 
a is a pointer to a WAVEFORM. 

is a waveform dimension; 0 is the first dimension. 


x 

d 

t is the position of an element of ordered (tuple) data; 
0 

b 


~ 


is the first position. 
is the number of bytes from the start of the waveform array; 
it is of type long. 


wave _prev(x) expands to the pointer to the previous waveform 
description block structure; 
use it as a WAVEFORM pointer 


+ $+ % + + 4+ 4 


+ % 


wave _subcnt(x) expands to the number of subsequent waveforms which 
point to this waveform as the previous waveform; 
use it as a short 


title ptr(x) expands to the pointer to the string header structure 
for waveform x; 
use aS a pointer to a char 


+ + + 4+ $+ F % F 


+ 


notes ptr(x) expands to the pointer to the notes area structure 
for waveform x; 
use as a pointer to a char 


wave flags(x) expands to the bit flags for special case handling; 
use it as a short integer 


wave size(x) expands to the total number of array elements 
associated with waveform x; 
use it as an long 


wave_elsize(x) expands to the number of bytes in the data element; 
use it as an long 


arr_ptr(x) expands to the pointer to the array associated with 
waveform x; 
use it as a BYTE pointer 


+ $+ $+ + HF + HF FF + Ft + RF FS 


+ + % 


wave dim(x) expands to the number of dimensions of waveform x; 
use it as a short integer 


dim_ptr(x) expands to the address of the array of W_DIM structures 
for waveform x; 
use it as a W_DIM pointer 


wave _tuple(x) expands to the number of elements of ordered (tuple) 
data for waveform x; 


+ + + + + 4 % F 
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use it as a short integer 


structures for waveform x; 


use it as a W_TUPLE pointer 
¥c ¥c vc ve ¥ ¥e ¥e ¥ ve vc ve vc ¥c ve 


* dim _flags(x,d) expands to the bit flags for special handling 
ar for dimension d of waveform x; 
use it as a short 


kid 

* ‘ 

* tuple ptr(x) expands to the address of the array of W_TUPLE 
ae 

ve 

bis 


* 
ve 
* dim_len(x,d) expands to the number of elements in dimension d 
' of the array associated with waveform x; 

™ use it as an long 

* 

* dim_inc(x,d) expands to the increment (in bytes) to the next element 
ag in dimension d of the array associated with waveform x; 
* use it as an long 


* dim_label(x,d) expands to the address of the structure with the 


- label information for dimension d of the array 

" associated with waveform x; 

use it as a char pointer 

* 

* dim _scale(x,d) expands to the multiplicative scale factor for 

ba dimension d of waveform x; 

bs use it as a double 

ve 

* dim_offset(x,d) expands to axis offset for dimension d of waveform 
. x; use it as a double 

* 

* dim_units(x,d) expands to the pointer to the string header for the 
* unit information of dimension d of waveform x; 

ba use it as a char pointer 

¥ 

* * ve ve ve ve bid ve ve ve ve id ve 


* tup_flags(x,t) expands to the bit flags for special handling for 
tuple t of waveform x; 
use it as a short 


* 


tup_type(x,t) expands to type of the data stored for tuple t of 
waveform x; 
use it as a short 


tup_index(x,t) expands to the offset (in bytes) to tuple t of 
waveform x from the first ordered element; 
use it as an long 


tup_label(x,t) expands to the address of the structure with the 
label information for tuple t of waveform x; 


use it as a char pointer 
tup_scale(x,t) expands to the multiplicative scale factor for © 


tuple t of waveform x; 
use it as a double 


+3 4+ + + + 4% + HF 4+ HF FHF OF 


tup_offset(x,t) expands to additive scale factor for tuple t of 
waveform x; 


+ + 4% + % 4 
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* use it as a double 


* tup_units(x,t) expands to the pointer to the string header for the 


7 unit information of tuple t of waveform x; 

¥ use it as a char pointer 

¥* 

cy ve vc ve ve ¥ ve ve ¥e ve ¥e ve ve 

vc 

* short _arr(x,b) expands to the address of the element located b 
* bytes from the beginning of the short array associated 
¥ with waveform x; 

bal use it as a short pointer 

* 

* long _arr(x,b) expands to the address of the element located b bytes 
¥ from the beginning of the long array associated with 

* waveform x; 

™ use it as a long pointer 

id 

* float. arr(x,b) expands to the address of the element located b 
* bytes from the beginning of the float array associated 
¥ with waveform x; 

bd 


use it as a float pointer 


+ 


* double arr(x,b) expands to the address of the element located b 

* bytes from the beginning of the double array associated 
= with waveform x; 

* use it as a double pointer 

vc 

¥ ¥c ve ve %* ¥ ve % vc ve rc ¥ ve 

* 

* The following are shorthand macros for getting information from the 
* substructures of waveform x when it is assumed that there is only 

* one dimension and one tuple. 

re 

* wave _len(x) expands to the number of elements in the first dimension 
” of waveform x; 

” use it as an long 

* 

* wave_inc(x) expands to the increment (in bytes) to the next element 
” in the first dimension of waveform x; 

¥ use it as an long 

¥e 

* wave _type(x) expands to the type of the first tuple data for 

cs waveform x; 

* use it as a short integer with values defined for 

ve 


tuple.t_type 
* 
He Fe Fe Fe He He Fe ae ae Ye Fe ae ve Fe Ye He Te He ve se Ye ve He te He Ye Ye Fe He He He ae ee He ae ae ae eae He Fe He Ae se ie He He He ae ae aie ae ve de Ve dee ae Me Me He He He Ae ae ae He ae / 


#define wave_prev(x) (x)->w_prev 
#define wave_subcnt(x) (x)->w_subcnt 
#define title ptr(x) (x)->w_title 
#define notes_ptr(x) (x)->w_notes 
#define wave_flags(x) (x)->w_flags 
#define wave_size(x) (x)->w_asize 
#define wave_elsize(x) (x)->w_elsize 
#define arr_ptr(x) (x)->w_aptr 
#define wave_dim(x) (x)->w_ndim 
#define dim_ptr(x) (x)->w_dimptr 
#define wave_tuple(x) (x)->w_ntuple 
#define tuple _ptr(x) (x)->w_tupleptr 
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#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


¥ 


ve 
ye 
ve 
vc 
* 
¥* 
* 
* 
* 
bid 


* 
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dptr_flags(x) 


dptr_len(x) 


dptr_next(x) 


dptr_label(x) 


dptr_scale(x) 


dptr_units(x) 


dim_flags(x,d) 
dim_len(x,d) 
dim_inc(x,d) 
dim_label(x,d) 
dim_scale(x,d) 
dim_offset(x,d) 
dim_units(x,d) 
tup_flags(x,t) 
tup_type(x,t) 
tup_index(x,t) 
tup_label(x,t) 
tup_scale(x,t) 
tup_offset(x,t) 
tup_units(x,t) 
short_arr(x,b) 
long_arr(x,b) 
float_arr(x,b) 
double arr(x,b) 
wave_len(x) 
wave_inc(x) 
wave_type(x) 


where: 


expands 


expands 


expands 


expands 


expands 


dptr_offset(x) expands 


expands 


((x)->w_dimptrt+(d))->d_flags 
((x)->w_dimptr+(d))- >d- _length 
((x)->w_dimptrt+(d))->d “nextel 
((x)->w_dimptrt(d))- >d_label 
((x)->w_dimptr+(d))->d_scale 
((x)->w_dimptr+(d))- >d_ offset 
((x)->w | dimptr+(d))- >d_ units 
(eyo >w_tupleptrt+(t))- >t_flags 
((x)->w_tupleptrt+(t))->t_type 
((x)->w_tupleptr+(t))->t_index 
((x)->w_tupleptrt+(t))->t_ ~ label 
((x)->w_tupleptrt+(t) )->t_ scale 
((x)->w_tupleptrt(t))- >t offset 
((x)->w_tupleptrt(t))->t_units 
(short *)((x)->w_aptrtb) 

(long *)((x)->w_aptrtb) 

(float *)((x)->w_aptrtb) 
(double *)((x)->w_aptrtb) 
(x)->w_dimptr~->d_length 
(x)->w_dimptr->d_nextel 
(x)->w_tupleptr->t_type 
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x is 
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a pointer to a W_DIM 


to the bit flags for special handling 
for dimension structure pointer to by x; 


use it as a short 


to the number of elements in the dimension; 


use it as an long 


to the increment (in bytes) to the next element 


in the dimension; 
use it as an long 


to the address of the structure with the label 
information for the dimension; 
use it as a char pointer 


to the multiplicative scale factor for 


the dimension; 
use it as a double 


to axis offset for the dimension; 


use it as a double 


to the pointer to the string header for the 
units information of the dimension; 
use it as a char pointer 


Ye ve ae Ye Fe ae We ae He Fee de ve ae Ye ie ae ve ae ae ie ae vi ae ae aie ae ae ee ve ae eae ae ee ae eae ie eae ae ae ee ve aie ae rae ae aie ae eae ae eae aie eae ee He a aie ae / 


#define 
#define 
#define 
#define 
#define 
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dptr_flags(x) 
dptr_len(x) 
dptr_next(x) 
dptr_label(x) 
dptr_scale(x) 


(x)->d_flags 
(x)->d_length 
(x)->d_nextel 
(x)->d_label 
(x)->d_scale 
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#define dptr_units(x) 
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(x)->d_offset 
(x)->d_units 
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* 


* Macros for getting information from the tuple structures 


* 


+ 


where: 


s x is a pointer to a W_TUPLE 


* tptr_flags(x) expands 


* 

vw 

* tptr_type(x) expands 
* 

* 

* tptr_index(x) expands 
* 

* 

* 

* tptr_label(x) expands 
* 

ve 

ve 

* tptr_scale(x) expands 
* 

* 

ve 

* tptr_offset(x) expands 
* 

¥ . 

* tptr_units(x) expands 
* 

* 

¥ 


to the bit flags for special handling for 
the tuple; 
use it as a short 


to the type of the data stored for the tuple; 
use it as a short 


to the offset (in bytes) to the tuple from the 
first ordered element; 
use it as an long 


to the address of the structure with the label 
information for the tuple; 
use it as a char pointer 


to the multiplicative scale factor for the 
tuple; 
use it as a double 


to additive scale factor for the tuple; 
use it as a double 


to the pointer to the string header for the 
units information of the tuple; 
use it as a STR_HDR pointer 


¥e ve Ye ve He ve ve ve ae ve ve ve ve Ye ie ae ae ve ae ae ie ve Ye ae ae ae ae ie ee ae ae ae He ve ve He ate He ae He Hee aie ae He He He He Ye He ae ae ae He He We Ye Ye ae ae de ae Ye He Ye Ye ye Fe / 


#define tptr_flags(x) 
#define tptr_type(x) 

#define tptr_index(x) 
#define tptr_label(x) 
#define tptr_scale(x) 
#define tptr_offset(x) 
#define tptr_units(x) 
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(x)->t_flags 
(x)->t_type 
(x)->t_index 
(x)->t_label 
(x)->t_scale 
(x)->t_offset 
(x)->t_units 
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0 x * 
el acq.bi ¥ 
* * 
9 Ye ve He He Ye He He Fe He He He Fe He Fe Fe Xe Fe Fe He Fe He He He Fe Fe He He Fe Fe Ye He He Fe Fe Ve He He He Fe Ve Fc He He He He He Fe He He Fe He He He Ke Ke Ke Ke $c Fe Fe ke He He ke he ke ek 
1% ¥e 
'*Version 1.0, Aug 24, 1988 * 
'* Copyright (c) Tektronix 1988 * 
9+ * 


U Ye te te eve te He te ae ae te Ye Ye He He He He He He He He He Fe We He He He He He He He He He He He He He He He He He He He He He He He He He He He He He He He He He We He He He He He He He He He HK / 


‘* acq.bi -- include file for SPD Waveform Acquisition 


‘'* Definition of POLL mode and Waveform sources 
CONST POLLZ = at’ 


CONST CH1% 
CONST CH2% 
CONST REF1% 
CONST REF2% 
CONST REF3% 
CONST REF4%Z 
CONST REF42220% = 2 
CONST ADDZ = 
CONST MULT% 
CONST CH1D% 
CONST CH2D% 
CONST ADDDZ 0 
CONST MULTDZ = 1 


'* waveform sources for the 11k family @ 


CONST TRACEZ = 1 
CONST STOZ% = 2 


6 
7 
8 
9 
1 
L 


'* waveform sources for the 2220/2221 
CONST ACQZ% = i, 

'* Acquisition modes for the 7912 
CONST ATCZ = 1 

CONST SAZ = 2 

CONST EDGEZ = 3 


** Acquisition sources for the 5223 


CONST LZ = 0 
CONST L1% = KJ 
CONST L2% = 2 
CONST RZ = 3 
CONST R1Z% = 4 
CONST R2% = be 


‘* Timeout values and meanings ® 


CONST TNONEZ 
CONST T10US% 
CONST T30USZ 
CONST T100US% 
CONST T300US% 


“un wt 
f£wWNrF O 
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CONST T1MSZ = 5 
CONST T3MSZ = 6 
CONST T10MSZ = 7 
CONST T30MSZ = 8 
CONST T100MSZ = 9 
CONST T300MS% = 10 
CONST T1SZ = 11 
CONST T3SZ = 12 
CONST T10SZ = 13 
CONST T30S% = 14 
CONST T100S2Z = 15 
CONST T300SZ = 16 
CONST T1000S% = 17 
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el eq fir.bi = 
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9 ¥ 
'*Version 1.0, Feb 2, 1988 * 
‘'* Copyright (c) Tektronix 1985 = 
Le 3 tv 


Pde de te ae a ae a oe ae ae ae ae ae ae aie He ae ae ae ae ae ae ae ae ae ae ae ae ate ae aie aie ae ae ae ae eae oie ae ie eee aie eae ee Fe ae aie aie ae aie aie ae ae ae ae de ae oe ee Hee ae / 


CONST MAXBANDS% = 10 
' Filter type to be designed 


CONST PASSSTOP% = 0 
CONST DIFF% #1 
CONST HILBERTZ =2 
CONST FUSER% = 3 
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1 ¥ 


‘a sp.bi ws 
¢ ve 
9 We oe vic ve oe ae oie ae ie ve aie aie aie ae vie ae ie ae ve ae aie aie aie ae He He ie ie ve He He Ve He ae ar He ae He He He He Hee He Ve He He He Te ae He He ve He He Fe Fe He He He ae ¥e He Xe Fe He Fe He Fe 
0 * ve 
'* Version 1.0, Feb 2, 1988 - 
'* Copyright (c) Tektronix 1988 me 


L] Fe dete te ve te ve te aie He ve He ve He ie vie te ae He vie aie ve ie vee ve ae te vie ie vie ie ve He ee ee ae Ye ae Yee vee vee re ve ae ae Hear ae ewe ae Ye ate Ye aie Yee We ae Ye He / 
'* This file contains common definitions used in signal processing 

** routines. 

'* general mathematical constants 


CONST PI# = 3.14159265358979323846 
CONST EXPO# = 2.71828182845904523536 
CONST SQRT2# = 1.41421356237309504880 


CONST HALFSQRT2# = 0.70710678118654752440 
‘* Polar and rectangular coordinate definitions 


CONST RADZ = 0 
CONST GRAD%Z = 1 
CONST DEGREEZ = 2 


'* End-of-Array algorithm selection codes. 
" ¥e 


"* REPEAT -- Repeat array ending value. All elements before the array 


“at start are equal in value to the first element Arr[0], and 

“- all elements after the array end are equal in value to the 

‘* last element Arr[N-1], where N is the length of the array. 

1 

'* BOUNCE -- "Bounce" off array ends to pick replacement value. 

"= Arr[{-i] is replaced with Arr[ti], and Arr[N-1+i] is replaced 
i with Arr[{N-1-i], where 0 < i <N. 

0 Xe : 

'* INVERT -- "Bounce and invert". Same as EA BOUN*CE, except the 

‘e sign of the selected element is changed. Thus, Arr[-i] 
*« is replaced with -Arr[ti], etc. 

0 Xe 

'* WRAP -- "Wrap" around from the end back to the start and wrap 

+ around from the start to the end. This makes the array appear 
oe "circular", as if the array was repeated over and over with 
ia the data values in the same order for each repetition. In 

ial this case, Arr[-i] is replaced with Arr[N-i], and Arr[N-1+i] 
a is replaced with Arr[i-1], where 0 < i <=N. 

"* 

‘%* ZERO -- An array element with subscript that is not in the array 
aid bounds is set to zero. So Arrf{i] = 0 if i< 0 or i >=N. 


CONST REPEAT% 
CONST BOUNCE% 
CONST INVERTZ 
CONST WRAP%Z 
CONST ZEROZ 


'* Windowing function selection codes 
8 ¥c 


nouuw wou 
—-WNnNr Oo 


te 

i RECTANGULAR =0.0 n= 0 to num 

'* TRIANGULAR =n/(num/2) n= 0 to num/2 

'¥ =num-n/ (num/2) n= num/2 to num-1 
‘ HANNING =.5*(1-cos(2*PI*n/num)) n= 0 to num-1 

ta HAMMING =.54-.46*cos(2*PI*n/num) n= 0 to num-1 
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'* BLACKMAN =.42-.5*cos(2*PI*n/num) + n= 0 to num-1l 
*n .08*cos(4*PI*n/num) 

§ 

'* FLATTOP =.36-.49*cos(2*PI*n/N) + n= 0 to num-l @ 
“ie .14*cos(4*PI*n/N) - 

re .01*cos(6*PI*n/N) n= 0 to N-1l 

9 

te 

Pe where: num = number of elements in array, if even; 
oe number of elements minus one, if odd 

we n = index of array element 


t ¥c 


CONST RECTANGULARZ 
CONST TRIANGULARZ 
CONST HANNINGZ 
CONST HAMMINGZ 
CONST BLACKMAN% 
CONST FLATTOP%Z = 


"« Square wave transitions types 
"¥ 


'* 


I 
Wf WoNr Oo 


‘te RAMP == transition edge is a sloped line: 

oe rising edge -- slope * time 

is falling edge-- amplitude + slope * time 

"* 

“a (a step wave can also be formed using 0 rise time and fall 
time ) 

oc 

‘Ss SL. “= transition edge is the integral of sin(x)**2: ® 
il rising edge -- integral of (2 * amplitude / pi) * sin(x)**2 
ee from x = 0 to x = theta, as theta ranges from 

ia 0 to pi 

ne falling edge-- integral of (2 * amplitude / pi) * sin(x)**2 
as from x = 0 to x = theta, as theta ranges from 

ne pi to 0 

CONST RAMP% vt 


CONST SIN2Z 4 


"* Symmetry conditions for convolution used in the differentiation 
1 


** NOSYM -- no symmetry involved 
" ¥ 
'* ODDSYM -- odd symmetry; h[n]) = -h[N-1-n) 


9 ¥e 


'* EVENSYM -- even symmetry; h[n] = h[N-1-n] 
CONST NOSYMZ = 0 
CONST ODDSYMZ = 1 
CONST EVENSYM%Z = 2 


‘* Type of interpolator to use for simple 1 point interpolation 
'* Two types are available. Sinc interpolation, and Lagrange inter- 


polation 

CONST SINCZ 0 

CONST LAGRANGE% 1 

'* Flag to indicate SUM or AVE in sumave. SUM will produce a sum, 
'* and AVE will average. 


CONST SUMZ 0 
CONST AVE% 1 
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'* Flag to indicate direction of search for waveform crossing. 
'* Used in the cross routine. 

CONST LEFTZ 
CONST RIGHTZ 


ton 
ay 


'* The following definitions are used to choose an interpolation fil- 
ter 

"* type in the routine w_interp.c. In addition to this, w_interp.c 
needs 

‘* SINC to be defined. This has been previously done for pt_interp.c 
CONST LINEARZ 


i 
CONST USERFILT%Z Z 


'* Flag to indicate which kind of analysis of histogram to use in 


pls_ hist 
CONST MODE% = 0 
CONST MEAN% = J, 
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# +e ve 
oe spd.bi * 
+ ve 
0 de ae oc oe ae He ve ve ve ve He ve de ve He or He He Ye Ye ae He He He Ve Ve ve He He He Ve He ve Ve ve ve He ve ve ve ve ve ve de ve ve ve ¥e Fe Fe He He He ve ¥e Ye He He Fe Ve Ye He He Ye ve ve Fe He He 
+ ve 
'* Version 1.0, Feb 2, 1988 - 
'* Copyright (c) Tektronix 1988 # 


U He te ve Ye Fe Ye ve Fe He He ve ve He He He ve He Ye Ye Ye He He He He He He Ye Fe Ye He He He He Ye Ye Ye Fe ve Fe He He He He Fe Fe Fe He He He He He He Fe Ye Ye He He He Fe He Ye He He Ye He Ye Fe Fe / 
'* This file contains the general definitions used throughout the SPD. 


'* General System Definitions 


CONST VERSIONS = "SPD V2.0" 
CONST TRUE% = 1 
CONST FALSEZ = 0 


'* Min and Max numeric values for the various number types 


CONST MINFLOAT! 
CONST MAXFLOAT! 


-~1.701411733192644270e38 
1.701411733192644270e38 


'% Error code definitions © 


CONST NOERROR% 
CONST WARNZ 
CONST FATALZ 
CONST CRASHZ 
CONST GRAPHERRZ 
CONST PARAMERR%Z 


CONST MINSHORT% = -32768 
CONST MAXSHORT% = 32767 
CONST MINLONG& = -2147483647 
CONST MAXLONGE& = 2147483647 


1oeuuw ti to 
Uf WNr © 
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'* tekgr.bi -- include file for SPD Graphing Function Package 


'* these are the default CGI colors 


CONST BLACK%Z = 0 
CONST WHITE% = I 
CONST REDZ = 2 
CONST GREEN%Z = 3 
CONST BLUEZ = 4 
CONST YELLOWZ = 5 
CONST CYANZ = 6 
CONST MAGENTAZ = 7 


'* these define the line styles 
CONST DEJAG% ft" 


CONST INTRP% = -2 
CONST WVFRMZ = me 
CONST INTRPDEJAGZ = -3 
CONST WVFRMDEJAGZ = -3 
CONST SOLID% = 1 
CONST LONGDASH4 = 2 
CONST DOTTEDZ = 3 
CONST DASHDOTTEDZ = 4 
CONST MEDDASHED% = 5 
CONST DASH2DOTS4Z = 6 
CONST SHORTDASH~ =7 


'* there are 6 available polymarker types 
CONST DOT = 
CONST CROSSZ 
CONST STARZ 
CONST SQUAREZ 
CONST XMRKR% 
CONST DIAMOND4 


tout weet 
Duff WH Fe 


'* an axis can be one of two types 
CONST LINAXIS% = 0 
CONST LOGAXIS% = 1 


'* text alignment options 
CONST LEFTJUSTZ 
CONST CENTERJUSTZ 
CONST RIGHTJUSTZ 
CONST BOTTOMJUSTZ 
CONST TOPJUSTZ 


iouu uu 
NONrFrO 


'* define options for setting graph type and text origin 
CONST DISPLAYGRAPH% 
CONST TEXTONLY% 


iL 


CONST XYVWPORTRELATIVEZ = 0 
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CONST XYDISPLAYRELATIVEZ = 1 


0 
i 
2 


'% define options for text alignment 


'* define grid types 
CONST NOGRIDZ 

CONST SOLIDGRID%Z 
CONST DOTTEDGRIDZ 


CONST UPPERLEFTZ = 1 
CONST UPPERRIGHTZ = 2 
CONST LOWERLEFTZ = 3 
CONST LOWERRIGHTZ = 4 
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'* Version 2.0, Aug 24, 1988 
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¥e big 
UJ Ye eve Ye Fe ve ae ae ae ae ve Ye Ye ve He He Ye He Fe Ye ie He ae He ae He vee ae ee Ae ae Ye ee ae He He Hee He ate ae He He He ae Ye Ye ae He He He Ye Ye Ye Fe He ve ae He He Me Ae Ye Ye Ye / 


' SINCLUDE: 'c:\tek\spd\include\eq fir.bi' 
' SINCLUDE: 'c:\tek\spd\include\sp.bi’ 

' SINCLUDE: 'c:\tek\spd\include\spd.bi' 

'" SINCLUDE: 'c:\tek\spd\include\tekgr.bi' 
' SINCLUDE: 'c:\tek\spd\include\wav.bi' 


DECLARE SUB bafiletowf(filenmS, bwave%Z,statusZ) 

DECLARE SUB barriltowf(SEG y AS ANY,dimlené&, tuptype% ,wavez,status4) 
DECLARE SUB barrtowf(SEG y AS ANY,ndims%,dimarr% ,ntupsZ, tup- 
type& ,wavez, statusz ) 

DECLARE SUB bclrerr(errnumZ, status) 

DECLARE SUB bconvolve(h%,x%,skiplen&,sym%Z,eoaaz,y%,statusZ) 
DECLARE SUB bcopywf(inwaveZ, outwavewavezZ,status2 ) 

DECLARE SUB bcpxadd(brel%,bim1%, bre2% , bim2% , broutwavezZ , biout- 
waves, statusé ) 

DECLARE SUB bcpxdiv(brel%,bim1%,bre2%,bim2Z, broutwaveé , biout- 
waved, Status4) 

DECLARE SUB bepxmult(brel%,bim1%,bre2% ,bim2% , broutwavez , biout- 
waves, sStatuszZ ) 

DECLARE SUB bcpxsub(brel%,bim1%,bre2% ,bim2% , broutwavez, biout- 
waves, Status& ) 

DECLARE SUB bcreatelwf(length&, tuptyp% ,wave%, status%) 

DECLARE SUB bcreatewf(ndimens%,dimenarr&,ntups%, tuparr% ,wavezZ,statusz) 
DECLARE SUB bcross(in- 

waves,start&,dir%, level#,ncross%,n%,eoaa%, arr#,statusZ) 
DECLARE SUB bdftowf(filenmS, ab%,intyp%, outwavetypZ,sof- 

tenZz, first% ,wave%, statusZ) 

DECLARE SUB bdiff(inwaveZ ,NZ, eoaa%, outwaveZ, statusZ) 

DECLARE SUB bdimlabel(wave%,dimennumZ, labelS, length%, statusZ) 
DECLARE SUB bdimlen(wave% ,dimennum%Z ,dimenlen%,statusZ) 
DECLARE SUB bdimreorder(wave% ,ndimens%,orderz,delkeepZ,sub- 
waves, Status) 

DECLARE SUB bdimunits(wave%,dimennumZ,units$, Length%, status) 
DECLARE SUB bdisablfpe() 

DECLARE SUB benablfpe(switchZ) 

DECLARE SUB beqfir(nbands%,ftyp%, flenZ , bwght#, bmag#, bup- 
per#, blower#, fullhZ ,h%, ext%, dev#, statusZ) 

DECLARE SUB berrfile(name$, status) 

DECLARE SUB bfconv(x%,y4,z%4,status4) 

DECLARE SUB bfcorr(x%,y%,z%4,status2) 

DECLARE SUB bfft(rtime%,itime%,rfreq%z,ifreq%,statusZ) 

DECLARE SUB bfiletowf(inS, outwave%,status% ) 

DECLARE SUB bfreewf(wave%,statusZ) 

DECLARE SUB bgraddcv(curvenumZ ,xsetnumZ, yset- 

numZ, Linecolour%, linetyp%,statusZ) 

DECLARE SUB bgraddmk(curvenumZ,xsetnumZ,yset- 

numZ ,mrkrcolour% ,mrkrtyp%, status) 

DECLARE SUB bgrautoscale(axis%Z,statusZ) 

DECLARE SUB bgrautotics(axis%,statusZ) 

DECLARE SUB bgraxclr(axiscolour%’,status4) 
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DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 


SUB 
SUB 
SUB 
SUB 
SUB 
SUB 


bgraxes(xaxistyp%,yaxistyp%, status) 
bgrback(r%,g%,b%,statusZ) 
bgrbox(colour%,statusZ) 
bgrclear(statusZ) 

bgrclose(statusZ) 

bgrcurv(curvenumZ ,xsetnumZ, yset- 


numéZ, linecolour%, linetypZ, statusZ) 


DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 


SUB 
SUB 


berdefa(setnumZ,start#, ending#, status) 
bgrdefd(setnumZ ,npts%, darray#,status%) 
berdeff(setnumé ,npts%, farray! ,status2Z) 
bgrdefw(setnumZ ,wvformZ,statusZ) 
bgerdev(deviceS, statusZ) 
berdsply(statusZ) 
bgrframe(colourZ,status2Z) 
bgrgrid(xcolour%,xstyle%, ycolour%,ystyle%,statusZ) 
bgrhan(status%, devhandlezZ) 
bgrindent(xindent%, yindent%, statusZ ) 
bgrinit(statusZ) 
bgrlegnd(colour%,corner%,status%Z) 
bgerlgnst(curve%, lstringS,statusZ ) 
bgermrkr(curvenumZ , xsetnumZ, yset- 


numéZ,mrkrcolour% ,mrkrtyp%Z,statusZ) 


DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 


bgrtext(notenumZ,text$,xpos%,ypos%Z,heightZ,colour%Z,xalign%,yalign%, angl 


SUB 
SUB 
SUB 
SUB 
SUB 
SUB 


eZ, statusZ) 


DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 


bplsamp(wave%, lead&, trail&, refndx&,nav%, eoaa%, ctrlevel#, reflevel#,statu 


skh) 


SUB 
SUB 
SUB 
SUB 
SUB 
SUB 
SUB 
SUB 
SUB 
SUB 


SUB 


bgrowo(ndx%, status2) 

bgrpause(statusé ) 

bgrreset (status) 
bgrsize(ticper#, axlabper#, subper#,titlper#,statusZ) 
bgrstitl(stitl$,colour%,statusZ) 


bgrtitle(titleS,colour%,statusZ) 

bgrtxorg (orgmodeZ,statusZ) 
bgertype(gtyp%,statusZ) 

bgruncurv(setnumZ, status) 
bgrundef(setnumZ,statusZ) 
bgrupdate(statusZ) 

bgrvwpt (xminwave%, yminwaveZ , xmaxz , ymax%, StatusZ ) 
bgrxlabl(labelS,colour%, status) 
bgrxrang (xmin#, xmax#, status4) 
berxtics(major#,minor#,status%) 
bgrylabl(labelS,colour%, status) 
bgeryrang (ymin#, ymax#, statusZ ) 
bgrytics(major#,minor#,statusZ) 
bifft(rfreq%,ifreqz,rtimez,itime%,statusZ) 
binitbin(seed&) 

binitgaus (seed&) 

binitunif(seed&) 
bintegrate(inwave%, eoaaz , outwave%Z, statusZ) 
birfft(rfreqZ,ifreqz,time%, statusZ) 
bmakesubwf (waveZ , subwaveZ , statusZ ) 
bmaketarget(inwave%, outwavewavez, status) 
bmeanstd(wavz ,mean#, std#, var#, rms#, statusZ) 
bminmax(wavZ ,minvalu#,maxvalu#,minloc&,maxloc&, status%Z) 
bnotesptr(waveZ% ,notesS, length%, status%Z) 


DECLARE SUB bplscalc(wave%, lndx&, rndx&,dirz, top#, bot- 
tom#,nz%,eoaaz, tlevel#, params#, status) 

DECLARE SUB bplsdutyf(wave%, lndx&, rndx&, dir%, num- 
samplesZ%, dutyf#, status% ) 
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DECLARE SUB 

bplsedge(wavez, lndx&, rndx&,dirz,n%,eoaaz%, lead&, trail&, lead2&,statusZ) 
DECLARE SUB bplsftime(waveZ%, lndx&, rndx&,dirZ, top#, bot- 
tom#,n%,eoaa%, tlevel#, arr#, status) 

DECLARE SUB bplshist(wave%, lndx&, rndx&,hist%,nbins%, top#, bot- 

tom, status’) 

DECLARE SUB 

bplsmeas (wave%, lndx&, rndx&,dir%z,histz,n%,eoaaz, tlevel#, params#, status ) 


DECLARE SUB bplsnegpk (waveZ, lndx&, rndx&, pkloc#, pkvalu#, status ) 
DECLARE SUB bplspamp(wave2Z, lndx&, rndx&,dirz,nav%,n%, eoaaz, top#, bot - 
tom, statusZ ) 

DECLARE SUB bplsperiod(wave%, lndx&, rndx&, dir’ ,num- 
samples% , period#, status%) 

DECLARE SUB 

bplspkfind(wave%, lndx&, rndx&,dir%, relamp#, fract#,eoaaz, pkloc#, pkamp#, st 
atusZ) 

DECLARE SUB bplspospk (wavez, lndx&, rndx&, pk loc#, pkvalu#, statusd ) 
DECLARE SUB bplsrtime(wave%Z, lndx&, rndx&,dir%, top#, bot- 
tom#,n%,eoaa%,tlevel#, arr#,status2Z) 

DECLARE SUB bpolar(real%,imZ,units%,un- 

wraps ,delay#,mag%,phaseZ, status) 

DECLARE SUB bptinterp(inwave%, flag%, p#,n%,eoaa%, valu#, status) 
DECLARE SUB brandb(prob#,number# ) 

DECLARE SUB brandg(mean#, std#,number# ) 

DECLARE SUB brandu(number#) 

DECLARE SUB brdimoffset(wavez,dimennumZ ,offset#,statusZ ) 

DECLARE SUB brdimscale(wave%,dimennumZ ,scale#,statusz ) 

DECLARE SUB breadnum(waveZ,tupleZ ,ndx&,num#, status% ) 

DECLARE SUB brectang(mag%, phase%, units%,delay#,realz%,imZz,status4) 
DECLARE SUB brfft(time%,rfreq%z,ifreq%z,statusz) 

DECLARE SUB brptcount(errtyp%, errcounté&, errmsgS ) 

DECLARE SUB brpterr(errtyp%,errmsg$) 

DECLARE SUB brtupoffset(wave%,tuple%, offset#, status’) 

DECLARE SUB brtupscale(wave%Z,tuplez,scale#,status%) 

DECLARE SUB bseterr(filenm$) 

DECLARE SUB bshutdown 

DECLARE SUB bsin2(ampl#, pwidth#, pkpoint#,dc#,wavez, status2) 
DECLARE SUB bsinc(ampl#, freq#, pkpoint#,dc#,wavez,status%) 

DECLARE SUB 

bsinemeas (wave%Z, wndow%, thresh#, phunit% , ampl#, freq#, phase#, status) 
DECLARE SUB bsinewave(ampl#, freq#, phase#,dc#,wavez,statuss) 
DECLARE SUB bsquarewave(amp#,period#,of- 
fset#,delay#,duty#,risetyp%, risetime#, falltyp%, falltime#,wave%z, status) 


DECLARE SUB bstateb(status4) 

DECLARE SUB bstateg(status2Z) 

DECLARE SUB bstateu(statusZ) 

DECLARE SUB bsumave(inwave%, flagword% , sumdimen% , outwavez, status ) 
DECLARE SUB btaper(inwav%,wd%, per#, outwavewavz, statusz ) 
DECLARE SUB btitlept(wave%,titleS, length, statusZ) 

DECLARE SUB btuplabel(wave% ,ndx%, labelS$, length%, status) 
DECLARE SUB btupreorder(wave% ,ntupsz, order%,delkeep%, subwavez, 
statusZ) 

DECLARE SUB btuptyp(wave%,tuple%, tuptypZ, status2 ) 

DECLARE SUB btupunits(wave%,ndx%, unitsS, length, status< ) 
DECLARE SUB bvalidcheck(wave%,statusZ) 

DECLARE SUB bwadd(inl%,in2%, outwave%Z, status) 

DECLARE SUB bwavedim(wave% ,numdimensZ,status2Z) 

DECLARE SUB bwavelen(wave%,wavelen&, status) 

DECLARE SUB bwavetuple(wave% ,numel%,statuszZ) 
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DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 


SUB 
SUB 
SUB 
SUB 
SUB 
SUB 
SUB 
SUB 


bwavetyp(waveZ,typz,statusZ) 
bwceadd(inwavez, constant#, outwaveZ,statusZ) 
bwediv(inwave% , constant#, outwaveZ, statusZ ) 
bwemax(inwaveZ, constant#, outwaveZ,status2Z) 
bwemin(inwavezZ, constant#, outwave%,statusZ ) 
bwemult (inwaveZ, constant#, outwaveZ,statusZ ) 
bwcsub(inwaveZ , constant#, outwaveZ, status) 
bwdecimate(binwave%,decfactor%, firstel&, bout- 


wavewaveZ,status%Z) 


DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 


bwdimoffset (wave% , dimennumZ , offset#,statusZ) 
bwdimscale(waveZ ,dimennumZ , scale#, statusZ) 
bwdiv(inl%,in2%, outwave%Z, status%Z) 
bwexp(inwave% ,nbase#, outwavez,statusZ) 
bwfdlabel(labelS ,dimennumZ , bwave%, status% ) 
bwfdunits(unitsS,dimennumZ , bwave% ,status% ) 
bwfnotes (notesS, bwavez, statusZ) 
bwftitle(titleS,bwavez%,statusZ) 
bwftlabel(labelS, tupnumZ , bwave%, status2) 
bwftoarr(wavez,SEG y AS ANY,statusZ) 
bwftoafile(bwaveZ%Z, annotatez, filenmS, statusZ) 
bwftofile(inwave%Z, outwaveS, statusZ) 
bwftunits(unitsS, tupnumZ , bwavez, statusZ ) 
bwinterp(inwf%, flagz,factor%, filtlen%, arr#, eoaaz, out- 


wavewfZ, statusZ) 


DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 
DECLARE SUB 


bwlog (inwaved ,nbase#, outwave% ,statusZ ) 
bwmax(inl%,in2%, outwave%, statusZ) 
bwmin(inl%,in2%,outwaveZ,statusZ) 
bwmult(inl%,in2%,outwavez, status) 
bwpower (inwavezZ, expon#, outwaveZ, status) 
bwritenum(num#, tupleZ ,ndx&,wave%, statusZ ) 
bwsqrt(inwaveZ, outwave%, status) 
bwsub(in1l1%,in2Z%, outwave%, statusZ) 
bwtupoffset(wavez,tupleZ,offset#,statusZ) 
bwtupscale(wavezZ,tuplez, scale#, status2Z) 
bzonedim(waveZ,dimenz ,begin&, ending&, delkeepZ, sub- 


waves, StatusZ) 


DECLARE 
DECLARE 
izeZ); 
DECLARE 
izeZ); 
DECLARE 
izeZ); 
DECLARE 
izez); 
DECLARE 


SUB 
SUB 


SUB 


SUB 
SUB 


SUB 


bget2220 (wavez% ,wtype% ,source%, address%, timeout) ; 
bget2230(wavez ,wtype% , source%, address%, timeoutZ ,normal- 


bget2430(wave% ,wtype%, source’, address%Z, timeout% , normal - 


bget7D20(wave% ,wtype% , source%, address%, timeout% , normal - 
bget5223 (wavez ,wtypez, sourceZ, address%Z, timeout%,normal- 


bgetll1lK(waveZ,wtypez,source% ,wavenumi4, ad- 


dressZ,timeout%,normalizez); 


DECLARE SUB 


bget7912(wavez ,wtypez ,modez, avg_count%, ad- 


dressZ,timeout% ,normalizeZ); 


DECLARE SUB 
izeZ); 


bget7854 (wavez ,wtype% , source%, addressZ, timeout% ,normal- 


DECLARE SUB bgetRTD710(wavez ,wtype%, source%, location%Z, ad- 
dressz,timeout%,normalizeZ) ; 
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CONST DIGLEVELSS 
CONST VOLTSS 


"Dig Levels" 
"Volts" 


'* Defines for keeping/deleting-the-source-wf flagword 
CONST KEEP? = 
CONST DELETE% = 1 


‘* Defines for copying/linking to waveform strings 
CONST LINK% = 0 
CONST COPY2 = 1 


‘* Defines for maximun number of dimensions and tuples 
CONST MAXDIMS% 10 
CONST MAXTUPS% 256 


'* Defines for tuptype 
CONST WUNDEFZ = 
CONST WSHORTZ 
CONST WLONG2 
CONST WFLOATZ 
CONST WDOUBLE% 


Sf WNFr © 
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Appendix D 


Suggested 
References 


Microsoft QuickBASIC 4.0 BASIC Language Reference, Microsoft Corporation, 
1987. 


Ramirez, Robert W., The FFT, Fundamentals and Concepts, New Jersey: Pren- 
tice-Hall, Inc., 1985. 


Microsoft C Language Library Reference, Microsoft Corporation, 1984-1987. 
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Appendix E 
ADIF File Format 


Introduction 


The Analog Data Interchange Format (ADIF) is intended to facilitate the shar- 
ing of waveform and other analog information between various software pack- 
ages and instruments supporting it. It is flexible, extendable, and can 
accommodate a wide range of data structures and formats. 


ADIF is a data object description language that ‘packages’ a description of the 
data along with the data itself. A minimum of information about the data is re- 
quired, but a wide and rich range of optionally associated information is per- 
mitted. ADIF is capable of representing very complex data dimensioned sets, 
but its block structure permits simple data sets to be represented in a simple and 
easy to understand manner. 


ADIF is hierarchically structured, and as such, can be subordinate to other struc- 
tures. It is suitable as a file format and can be easily transmitted across IEEE 
488.1 / IEEE 488.2, RS-232, SCSI, Ethernet, and various other transmission 
media and protocols. 


While ADIF can represent digital and other kinds of structured data, it is some- 
what cumbersome. The accommodation of digital data is one of several possible 
extensions to ADIF. 


This document is not a rigorous definition of ADIF; it is intended to be 

readable and understandable. However, there should be little ambiguity. Much 
of the ADIF specification relies on definitions rigorously set forth in other stand- 
ards, particularly IEEE 488.2, Codes, Formats, Protocols and Common Com- 
mands. 
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Overview 


ADIF is block-structured. An ADIF data set generally consists of several 

description blocks and a data block. A block typically contains keywords with 

values as well as subordinate blocks. Keywords may have one or more values. 

Some blocks require modifiers. Modifiers allow a block to have a value as well @} 
as contain keywords and subordinate blocks. Modifiers also allow multiples of 

the same block type to be uniquely distinguished form one another. 


Each block addresses a different aspect of data description. The DATA block, 
naturally, contains the data of primary interest. The IDENTIFY block describes 
the environment and manner in which the data was obtained. The DIMEN- 
SION and ENCODE blocks describe how the data are physically represented 
and logically organized. The TRACE and VIEW blocks provide semantic infor- 
mation about the data. A REMARK block accommodates arbitrary text infor- 
mation and a LEGAL block is for lawyers to play with. Finally, the revision 
level of the ADIF standard itself and any optional protocols used are described 
in the STD block. 


ADIF focuses on data as an abstraction of instrument or algorithmically 

gencrated data. The method and manner of data acquisition or creation is hand- 

led as descriptive information not required for proper interpretation of the data. 

For example, instrument dependent settings and characteristics, such as sample 

rate, are translated into acquisition device independent parameters such as o 
precision and resolution. 


Where it is essential the data acquisition or generation attributes or parameters 
be associated with the ADIF data, a separate but syntactically identical (but 
semantically different) data structure is recommended. Examples of such at- 
tributes are front panel settings or calibration data for the acquiring instrument. 
However, the effect of the instrument’s calibration should be reflected in the 
precision and resolution parameters in the ADIF data set. 


Relevant environmental conditions, such as ambient temperature are, however, 
accommodated by ADIF (see the DATAC(MEASUREMENTS) block). Informa- 


tion such as calibration data should be reflected in the precision and resolution 
of the data 


The ten basic blocks of the ADIF format are: 


STD Specifies the version of the ADIF standard used to create 
the ADIF data set, as well as any optional protocols. 


IDENTIFY Names the data set and describes the environment in 
which it was generated. Environment description in- 
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LEGAL 


REMARK 


DIMENSION 


ORDER 


ENCODE 


TRACE 


VIEW 


DATA 
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cludes project name, test number and series, date and 
time, and source. 


Arbitrary text for legal consumption. Such things as 
copyright, trademark and ownership can be specified. 


Arbitrary text to be read by people. 


Dimension blocks specify the structure and format of 
data in the DATA(CURVE) blocks. Provision is made 
for data scaling, offset, naming, and units specification. 
The DIMENSION, ENCODE and ORDER blocks, 
taken together, completely describe the structure and 
physical format of the data in the DATA(CURVE) 
blocks. 


A dimension may be either explicit or implicit. An im- 
plicit dimension is one represented by a function instead 
of actual data values. A waveform represented by volt- 
age readings taken at a constant time interval is an ex- 
ample of a data set with an implicit and explicit 
dimension. The implicit dimension is the time dimension 
and is represented by a function instead of data values. 
The voltage dimension is explicit, with values present in 
the DATA(CURVE) blocks. 


Specifies the DATA(CURVE) block ordering of the data 
elements for each dimension. 


Specifies the encoding format for data in the DATA and 
ENCODE blocks. Also covered are signal values for un- 
derflow, overflow and no value, as well as the range and 
precision of the data. 


Logically groups dimensions as functions, surfaces, sets, 
etc. TRACE blocks provide semantic information about 
the data and are used in the construction of VIEW 
blocks. They also provide a convenient and powerful 
mechanism for sub-setting data. 


VIEW blocks provide a second level of semantic informa- 
tion about the data. By describing logical relationships 
among traces defined in the TRACE block, complex 
valued waveforms, envelopes, polar waveforms, etc., can 
be easily described. 


The data. Different subordinate blocks described dimen- 
sioned data, pulse parameter measures, sine parameter 
measurements, statistical measurements, and point values. 
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Block and Keyword Organization 


The following listing of blocks and keywords show the ADIF hierarchical struc- 

ture. Blocks are followed by a pair of parenthesis. Required blocks and 

keywords are shown in boldface. If a keyword is boldface, but the block is not, 

the keyword is required only if the block is present. A block followed by an ellip- 8 
sis is a repeat of a previous definition; If multiple occurrences of a block or 

keyword are permitted, it is marked with "[m]". 


The ADIF standard and revision control block: 
STD () 
VERSION 
PROTOCOLS 


The ADIF environment description blocks: 
IDENTIFY () 
NAME 
TECHNICIAN 
PROJECT 
DATE 
TIME @ 
UUT () 
ID 
NAME 
DESIGN 
TES! () 
NAME 
SERIES 
NUMBER 
SOURCE () 
INSTRUMENTS 
HISTORY 
PACKAGES 
NOTE 
LEGAL () | 
COPYRIGHT 
TRADEMARKS & 
OWNERSHIP 
CLASSIFY 
NOTE 
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REMARK () 
NOTE 
INFORMATION 


The ADIF data structure and format blocks: 
DIMENSION = <dimension label> ()[m] 
NAME 
UNITS 
SCALE 
OFFSET 
SIZE 
TYPE 
FUNCTION () 
LINEAR 
SINE 
COSINE 
TANGENT 
EXP 
LN 
LOG 
© GENERAL 
ENCODE ()... 
NOTE 
ORDER () 
TYPE 
SEQUENCE 
ENCODE () 
FORMAT 
NOVALUE 
OVERRANGE 
UNDERRANGE 
HIRANGE 
LOWRANGE 
RESOLUTION 
PRECISION () 
LENGTH 
@ ot 


NOTE 
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The ADIF blocks for semantic information: 


TRACE = <trace label> ()[m] 
NAME 
INDEPENDENT () 


DIMENSION ()[m] @ 
LABEL 
START 


STOP 
DEPENDENT () 
DIMENSION ()[m] 
LABEL 
SYMMETRY 
NOTE 
VIEW = <view label> ()[m] 
NAME 
ENVELOPE () 
UPPER 
LOWER 
FUNCTION 
COMPLEX () 
REAL ® 
IMAGINARY 
POLAR () 
MAGNITUDE 
PHASE 
BODE () 
MAGNITUDE 
PHASE 
SET () 
NAME 
ATTRIBUTE 
ELEMENTS 
NOTE 


The ADIF data block: 


DATA = <data label> ()[m] 
DELTA () 


DIMENSION ()[m] 
LABEL 
SCALE 
OFFSET 
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SIZE 
IDENTIFY () ... 
ENCODE ()... 
CURVE () 

VALUES 

SUMCHECK 

CHECKTYPE 

NOTE 
PULSE = <pulse label> ()[m] 

NAME 

TRACE 

START 

STOP 

AMPLITUDE 

WIDTH 

DUTYFACTOR 

~ PERIOD 

RISE 

FALL 

RPROXIMAL 

RDISTAL 

RMESIAL 

FPROXIMAL 

FDISTAL 

FMESIAL 

PROXIMALPCT 

DISTALPCT 

MESIALPCT 

EOAA 

SUMCHECK 

CHECKTYPE 

NOTE 

SINE = <sine label>()[m] 
NAME 
TRACE 
START 
@ STOP 
AMPLITUDE 
FREQUENCY 
PHASE 
UNITS 
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SUMCHECK 
CHECKTYPE 
NOTE 
STATISTICS = <statistics label>()[m] 
NAME 
TRACE 
START 
STOP 
MAXIMUM 
MINIMUM 
MEAN 
DEVIATION 
SUMCHECK 
CHECKTYPE 
NOTE 
POINT = <point label>()[m] 
NAME 
UNITS 
LOCATION() 
LABEL 
INDEX 
TRACE 
PARAMETER () 
VALUE 
UNITS 
VALUES 
SUMCHECK 
CHECKTYPE 
NOTE 
MEASUREMENTS = <measurements label>()[m] 
NAME 


PARAMETER () 
VALUE 
UNITS 
VALUES 
SUMCHECK 
CHECKTYPE 
NOTE 
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Syntax 


ADIF is block structured and uses a syntax similar to the Lisp and C languages - 
but much simpler and more easily understood. Each hierarchical level is intro- 
duced by a block name, with its subordinate elements enclosed in parenthesis. 
A block may have a modifier and may contain subordinate blocks, keyword 
units, or both. Keyword units consist of a keyword followed by one or more 
values. Keyword units are separated by a vertical bar (|). If a keyword has 
more than one value, the values are separated by commas. White space may 
generally appear anywhere except within block names, keywords, and most 
values. 


ADIF(STD (VER 1.0) | 
IDENT (NAM "ADIF Example" | TEST (NUM "7D4", "2.4") ) | 
DIM=X (SCALE 0.01 | TYPE IMPLICIT | SIZE 5) | 
DIM=Y (SCALE 0.02 | OFFSET 0.1 | TYPE EXP | 
ENCODE (FORMAT INTS8) 
» | 
DIM=Z (SCALE 0.001 | TYPE EXPLICIT) | 
ENCODE (FORMAT INT32) | 
DATA 
(CUR 
(VAL 2.1, 3, 4.23, 3.9, 1.02, .002, -1.2E-4, -12.01, 
-13836, -23.45) 


Fig E-1. Simple ADIF example. 


The ADIF syntax is valid IEEE 488.2 syntax but ADIF uses the expression syn- 
tax of 488.2 instead of the more common command header syntax. This is be- 
cause ADIF addresses problems impossible to solve using IEEE 488.2 command 
header syntax. For example, it is impossible to send an ADIF file to a named 
destination, or send two ADIF data objects together in the same message using 
a single IEEE 488.2 command. 


The problem arises from the fact that an ADIF object is very much like a 
numeric value, such as NR1. IEEE 488.2, however, provides no mechanism, ex- 
cept expressions, for structured values. 


Syntactic Elements 


The format for the elemental ADIF syntactic elements are in most cases identi- 
cal to or a subset of types in IEEE 488.2. The same diagramming conventions 
are also used (IEEE 488.2 7.2.1). 
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Character Set 


ADIF character information is ASCII as defined by ANSI X3.4-1977. Charac- 
ters are eight bits, but only the low order bits are significant; the high order bit 
should be zero. 


White Space 


White space is defined by IEEE 488.2 (7.4.1.2) and includes ASCII characters in 
the range (0-9 and 11-32 decimal). Newline is excluded; Carriage Return 
(decimal 13) is recommended for "pretty print" formatting. 


White space is generally optional and may appear anywhere except within a 
block name or keyword. White space may also not appear within a value except 
for quoted strings and Hexadecimal Bit numbers. These may contain certain 
wnite space characters specifically allowed by IEEE 488.2. 


Blocks, Block Modifiers, and Keywords 


Block names, block modifiers, and keywords conform to the IEEE 488.2 rules 
for Simple Command Program Header (7.6.1.2) with the additional restriction 


that all alpha characters be upper case. 8 


Block names, block modifiers, and keywords consist of the alpha-numeric charac- 
ters and underscore (_), and are limited to 12 characters. They can be ab- 
breviated by truncation to three leading characters. 


Values 


ADIF employs a limited set of well defined value types. These include IEEE 
488.2 Response Data (8.7), with some additional restrictions, and Hexadecimal 
Bit Numbers, which are defined below. 


Suings 
—_L. 


String values conform to IEEE 488.2 String Program Data (7.7.5) with the 

restriction that they must be delimited by double quotes ("). They may also be 

restricted to maximum lengths of 8, 32 or 224 characters, depending on the par- 

ticular keyword for which they are a value. These are designated as types "string 

8", "string 32", and "string 255". (The “odd" length of 224 guarantees up to 7 ® 
type string32 substrings, along with a length or delimiter byte, can be accom- 

modated by a string of 255 bytes or less). 
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Some keywords allowing multiple string values have the additional restriction of 
limiting the total character count of all string values to within a specified limit. 


Examples: 


"Any ASCII text in the range 32" 
"to 127 (decimal) is permitted" 
"Note, however, the double" 

“ quote character ("") must be" 

" doubled if embedded" 


Date 


Date is a special format string defined by Tektronix Codes and Formats. 


The format is YY YY-MM-DD, where YYYY is a full 4 digit year. MM is the 
month (01 to 12), and DD is the day (01 to 31 or less, depending on month). 
MM and DD must be two digit positive NR1 values, with leading zeros as re- 
quired. YY YY must be a four digit positive NR1 value, with leading zeros as re- 
quired. 


Example for March 6, 1988: 


"1988-03-06" 
Time 
Date is a special format string defined by Tektronix Codes and Formats. 


The format is HH:MM:SS.s, where HH is hours from 00 to 23 and MM is 
minutes from 00 to 59. HH and MM must be two digit positive NR1 values, 
with leading zeros as required. SS.s is seconds from 00 to less than 60. SS.s 
must be positive NR1 or NR2, with the additional restriction that the integer 
portion must be exactly two digits, with leading zeros as required. The fraction- 
al portion is optional. 


Examples: 
"23:02:09.173" 
"04:59:59" 

Label 


The Label value type is identical in format to IEEE 488.2 Character Response 
Data (8.7.1). It consists of uppercase alpha characters, digit characters, and the 
underscore (_) character. It can be no more than 12 characters long and must 
begin with an alpha character. 


Examples: 
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en tata I 


A 
X1 
MOTHER IN LA 


Enumerated Sets 


Some keywords take as values one name from an enumerated set of names. - 
These names, which are listed for each keyword taking them, are not delimited 

in quotes. Like Label values, enumerated set names conform to the rules for 

IEEE 488.2 Character Response Data (8.7.1). 


Examples: 


CRC8& 
CRC16 
ITT 


Hexadecimal Bit Numbers 


Hexadecimal Bit Numbers do not conform to IEEE 488.2. They are similar to 
Non-Decimal Numeric Program Data (7.7.4). However, instead of representing 
a number in a particular radix, Hexadecimal Bit Numbers represent bit patterns 
using ASCII hexadecimal digits. Each digit represents the four bit pattern Cor- 
responding to the digit’s value; a sequence of digits represents a sequence of 4- 
bit groups. 


Hexadecimal Bit Numbers are introduced by a pound sign (#) followed by a rd 
capital X, and are terminated by the first non hexadecimal digit other than a 

space. The allowed hexadecimal digits are 0 through 9 and A through F (upper- 

case only). The binary patterns so represented are: 


ASCII Bit ASCII Bit 
Digit Pattern Digit Pattern 
0 0000 8 1000 

1 0001 9 1000 

£ 0010 A 1001 

3 0011 B 1010 

4 0100 Cc 1011 

5 0101 D 1100 

6 0110 B 1101 

7 0111 PF 1110 


Binary information represented in this fashion requires twice as much space as is 

needed for IEEE 488.2 Definite Length Arbitrary Block Response Data (8.7.9). 
However, only a small subset of the ASCII character set is used. This subset 

does not include ASCII control characters (range 0 to 1F), and is thus more & 
suitable for some transmission media such as RS-232. 


The interpretation of Hexadecimal Bit Numbers is determined by the ENCODE 
block. If the ENCODE block FORMAT keyword specifies INT32, the binary in- 
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formation is to be interpreted as groups of 32 bit integers; if FP64 is specified, 
each Hexadecimal Bit Number must contain 16 hexadecimal digits and is to be 
interpreted as the "bit image" of a 64 bit floating point number. 


The default value for FORMAT applies if FORMAT is not present in the EN- 
CODE block. 


The following are several examples of Hexadecimal Bit representations of the 
number 12875 (324B hex) for several values for FORMAT: 


INT16 #X324B 
SINT16 #X4B32 
INT32 #X0000324B 
SINT32 #X4B320000 


Note for INT16, the #X and the IEEE 488.2 #H (8.7.5) formats are identical, 
but not so with SINT16. The same number, 12875, would be represented by 
IEEE 488.2 Definite Length Arbitrary Block Response Data (8.7.9) as follows: 


INT16 #14 <0011 0010 0100 1011> 
SINT16 #14<0100 1011 0011 0010 


where the 16 bit binary numbers delimited by "<" and ">" occupy two character 
positions. 


NRI, NR2 and NR3 Value Types 


NR1, NR2, and NR3 Numeric Response Data types are defined by IEEE 488.2 
(8.712, 8.7.3, and 8.7.4, respectively). NR1 is a simple signed integer, NR2 is a 
simple signed real number without exponent, and NR3 is a real number with ex- 
ponent. 


NR1 examples: 
-2, 0, 32489, +3 
NR2 examples: 
-.1, -325.3294, 0, +0.0 .00452 
NR3 examples: 
~.04E-01, -12.6E +2, 0., .1E2, +1E2 


Numeric Value Type 


ADIF defines the term "Numeric" for value type to include the following IEEE 
488.2 Response Data types: 


@ NRi Numeric Response Data (8.7.2) 
@ NR2 Numeric Response Data (8.7.3) 
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NR3 Numeric Response Data (8.7.4) 
Hexadecimal Numeric Response Data (8.7.5) 


Octal Numeric Response Data (8.7.6) 


Binary Numeric Response Data (8.7.7) © 


Example of Hexadecimal Numeric Response Data for 6848 (decimal) : 


#H1ACO0 


Example of Octal Numeric Response Data for 6848 (decimal); note the use of Q 
instead of O: 


#Q15300 


Example of Binary Numeric Response Data for 6848 (decimal): 
#B1101011000000 


Extended Numeric Value Type 


The ADIF type "Extended Numeric" adds Hexadecimal Bit Numbers to the 
"Numeric" value types. 


Definite Length Arbitrary Block Response Data _ 


IEEE 488.2 Definite Length Arbitrary Block Response Data (8.7.9) is only al- 
lowed for DATA(CURVE(VALUES)). The interpretation of the eight-bit data 
values is determined by the FORMAT keyword in the applicable ENCODE 
block. The interpretation is similar to Hexadecimal Bit Numbers, except groups 
of eight bits are interpreted instead of four. See the example in the section on 
Hexadecimal Bit Numbers. 


Examples of Definite Length Arbitrary Block Data: 
#202 <2 binary bytes> 
#12 <2 binary bytes> 
#3402 <402 binary bytes> 
Semantic Rules 
most only one occurrence; other blocks can be specified multiple times. Some 


blocks and sub-blocks require modifiers, some don’t allow them, and modifiers 
are optional on others. 


Some blocks are required, some are optional. For some blocks there can be at @ 
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If a particular block is present, certain subordinate keywords may be required, al- 
though most are optional. Certain blocks and keyword parameters may require 
the presence of other blocks and or keyword parameters. These restrictions are 
noted in the description of each block and its keywords. 


© A block may be empty if it has no required keywords; that is, it may contain no 
keywords or subordinate blocks. If a keyword takes multiple values, all values 
must be of the same type. 


A few keywords have default values; if the keyword is omitted, the default value 
obtains. If a keyword is present, it must have a value or set of values. 


Where sequence is meaningful, such as in a simple file or the transmission of an 
ADIF data set, the STD block must be first. All DIMENSION, ENCODE, and 
ORDER blocks must precede all DATA blocks. All VIEW blocks must 
precede any TRACE blocks, and all TRACE blocks must precede all DATA 
blocks. Otherwise, blocks may appear in any order. 


Error Handling 


Where only one occurrence of a block, keyword, or value is allowed, or where 
only one from a group of blocks, keywords, or values is allowed, and where more 
than one is actually found, a warning indication is given and the last occurrence 
of the item is accepted. 


Where the error is forgivable, such as the sequencing of blocks, the user may 
choose to either accept (with a warning indication) or reject the ADIF data set. 


If required information is omitted, the user of the ADIF data set may reject the 
ADIF data set or accept it by giving a warning and choosing an appropriate sub- 
stitute for the missing information. 


In general, it is the responsibility of the user of an ADIF object to determine the 
action is to be taken when an invalid ADIF format is encountered. In all cases 
when an invalid ADIF format or construction is detected, a warning or error in- 
dication must be given. The form the warning or error signal takes depends on 
the hardware and software involved. It must be possible to determine the 
specific cause of each warning or error signal. 


This level of error handling is, of course, in addition to whatever requirements 
are imposed by any transmission medium, such as GPIB. 


Clearly, consumers, such as data analysis programs or instruments, are generally 
not able to handle all ADIF data sets. The data represented by the ADIF data 
set must be appropriate for the user. A program or instrument designed to 
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process two dimensional data must be presented with an ADIF data set contain- 

ing only two dimensional data, or for which there is a known VIEW or TRACE 
specifying an appropriate two dimensional subset of the data. The action to be 

taken when an inappropriate ADIF data set is presented to a user is determined 

by the user and is not part of the ADIF specification. ® 


An ADIF data set may (and often does) contain far more information than is of 
interest to the user. Extraneous or irrelevant information can and should be ig- 
nored by the user. 


A user should be able to handle any appropriate ADIF data set. The only excep- 
tion to this are the the special ENCODE(FORMAT) values. These are in- 
cluded as part of the ADIF specification due to the widespread use of hardware 
supporting these formats. Although support for them is highly recommended, 

an ADIF user necd not support these formats. If the user encounters these for- 
mats for data that is relevant, the ADIF data set can be rejected with an ap- 
propriate error indication. 


Changes and Extensions 


All changes to the ADIF specification are reflected in the VERSION and 
PROTOCOL keywords of the STD block. 


Changes and extensions to the ADIF specification are under the complete con- - 
trol of the Tektronix Product Communication Coordination office, formerly 
known as AICE. 


Encoding Syntax 


ADIF has very few syntactic elements. The previously defined elementary ele- 
ments are Values, Keywords, Block Names, and White Space. Four additional 


elementary elements are the Value Separator, Unit Separator, Block Unit Open, 
and Block Unit Close. 


Finally, ADIF defines three compound elements: Keyword Units, Block Units, 
and ADIF itself. 


The ADIF syntax diagrams follow the IEEE 488.2 Diagramming Syntactic Flow 
(le wo bh 


Value Separator _ 


The Value Separator is a comma (,), which may optionally be preceded and fol- 
lowed by white space. It is identical to the IEEE 488.2 Program Data Separator 
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(7.4.2). Successive occurrences of Value Separators are allowed; they are 
equivalent to a single occurrence. 
Unit Separator 


The Unit Separator is a vertical bar (|), which may optionally be preceded and 
followed by white space. Unit separators are not required for proper parsing of 
ADIF. However, their presence allows for better error handling if values are 
malformed and, more important, simplifies the translation of ADIF blocks into 
IEEE 488.2 syntax. Therefore, Unit Separators are required, but their omission 
is not an error. 


Unit Separators are similar to IEEE 488.2 Program Message Unit Separators 
(7.4.2). Successive occurrences of Unit Separators are allowed; they are 
equivalent to a single occurrence. 


Block Modifier Separator 

The Block Modifier Separator is an equal sign (=), which may optionally be 
preceded and followed by white space. Successive occurrences of Block 
Modifier Separators are allowed; they are equivalent to a single occurrence. 
Block Open 

The Block Open is an opening parenthesis ((), which may optionally be 
preceded and followed by white space. 

Block Close 


The Block Close is a closing parenthesis ()), which may optionally be preceded 
and followed by white space. 


Keyword Unit 


A Keyword Unit is defined as: 


Block Unit 


A Block Unit is defined as: 
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ADIF 


It is intended that ADIF can be a subordinate unit of a higher level but similarly 
organized (at least syntactically) structure. As such, it is defined as described in 
the following paragraphs, including a modifier that can be used to uniquely iden- 


tify it. © 


Upward Compatibility 


Note the ADIF syntax allows recognition of any syntactic element without resort 
to look-ahead. Any element, such as a block or keyword, can be easily skipped 
over by a parser not recognizing it or choosing to ignore it. As extensions are 
made to ADIF, older parsers can continue to handle ADIF data sets 


ADIF and IEEE 488.2 


The ADIF syntax is different from but compatible with the IEEE 488.2 syntax. 
In IEEE 488.2, parenthesis denote nestable expressions. While ADIF imposes 
its own rules within IEEE 488.2 expressions, they conform to the IEEE 488.2 
restrictions for expressions. The result is ADIF data objects can be transmitted 
via IEEE 488.1 / IEEE 488.2 (GPIB) without conflict or special conversion. 


ADIF does more than conform to the letter of the IEEE 488.2 law. The ADIF @ 
syntax is easily mapped onto the IEEE 488.2 syntax. With minor modifications, 

an IEEE 488.2 parser, or at least its syntax analyzer, can also analyze the syntax 

of an ADIF data set. 


ADIF Block Descriptions 


In the following descriptions, blocks and keywords must include the portion in 
boldface letters; the normal face portion can be truncated at any point. Value 
types are defined in the Syntax section. 


ADIF 


The entire ADIF data set is contained in an ADIF "super" block: 


ADIF = <data set label>( ) @ 
ADIF data sets may be identified by a <data set label> value. The value type is 
Label. Whether a <data set label> is required, and whether there may be multi- 
ple occurrences of ADIF data sets, and if so, whether the < data set label> must 
be unique, depends on the syntax and semantics of any higher level of organiza- 
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tion imposed. A data base or the device-dependent language of an instrument 
are examples of a higher level of organization. 


An ADIF data set is built from the following blocks. 


The STD Block 


To allow for compatibility, or at least to detect incompatibility, ADIF requires a 
STD block for each ADIF data set. To determine compatibility, an ADIF par- 
ser examines the STD block to determine if it can properly parse the ADIF data 
set. As changes and extensions are made to ADIF, the version number is incre- 
mented. At the time a parser is developed, it is known which earlier versions of 
ADIF are compatible and which are not. The same parser can also recognize 
later versions of ADIF and alert a user when it may not be compatible. 


This block can occur only once. It begins with 


STD 


and takes the following keywords: 


VERSION Specifies the version of the ADIF standard. This is an 
NR2 format number; the fractional part represents rela- 
tively minor revisions and extensions to the standard, and 
the integer part represents major changes. This keyword 
is required and may occur only once. 


PROTOCOLS = Specifies optional protocols or levels. This keyword may 
occur only once and takes the following enumerated 
values. 


There are no protocols currently defined. 
The IDENTIFY Block 


The IDENTIFY block contains fields uniquely identifying the data and describ- 
ing the environment in which it was created or acquired. The precise definitions 
for the contents of all text string values in the IDENTIFY block is left to the 
user. However, the general category must be followed. This block is optional 
but can occur only once. It begins with: 


IDENTIFY (...) 


and has the following keywords: 


NAME User defined name used to identify the entire ADIF data 
set. If no external naming mechanism is provided (such 
as a modifier to a higher level "ADIF" block), this field 
should be taken as the identifier for the ADIF data set. 
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Value type is text string 32. This field is optional, only 
one occurrence of the NAME keyword is allowed. Only 
one value is allowed. 


TECHNICIAN Identifies the technician(s) involved in the generation or 
modification of the data. Valuc type is text string 32. 
Only one occurrence of the TECHNICIAN keyword 1s al- @ 
lowed. Multiple values are allowed and imply an order- 
ing from most to least important. Total string count is 
limited to 224 characters. 


PROJECT Name of project, job, task, etc. Value type is text string 
| 32. Only one occurrence of PROJECT is allowed and 
only one value is allowed. 


DATE Date of data creation or acquisition. Value type is Date. 
Only one occurrence of the DATE keyword is allowed. 
One or two values are allowed; if two values are 
specified, they define an inclusive range of time. 


TIME Time of data creation or acquisition. Value type is Time. 
Only one occurrence of the TIME keyword is allowed. 
One or two values are allowed; if two values are 
specified, they define an inclusive range of time. 


UUT (... ) A description of the "unit under test". This block may 
occur only once and takes the following keywords: 


e 


Identification of the unit under test. Value type is 
text string 32. Only one occurrence of the ID 
keyword is allowed. Multiple values per keyword are 
allowed and imply an ordering from most to least im- 
portant. Total string count is limited to 224 charac- 
ters. 


NAME 


Name or type of unit under test. Value type is text 
string 32. Only one occurrence of the NAME 
keyword is allowed. NAME is similar in use to ID, 
except only one value is allowed. 


DESIGN 
Identifies the design specification. Value type is text 
string 32. Only one occurrence of the DESIGN 
keyword is allowed. Multiple values are allowed and 


imply an ordering from most to least important. 
Total string count is limited to 224 characters. @ 


TEST (... ) Test description. Only one occurrence of the TEST 
block is allowed. Defined keywords are: 
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SERIES 


Number or ID of test series. Value type is text string 
32. Only one occurrence of SERIES is allowed and 
only one value is allowed. 


NUMBER 


Number or ID of particular test. Value type is text 
string 32. Only one occurrence of the NUMBER 
keyword is allowed. Multiple values per keyword are 
allowed and imply an ordering from most to least im- 
portant. Total string count is limited to 224 charac- 
ters. 


NAME 


Test series name. Valuc type is text string 32. Only 
one occurrence of the NAME keyword is allowed. 


Data source, such as the instrument ID, program name, 
etc. Only one occurrence of the SOURCE block is al- 
lowed. Defined keywords are: 


HISTORY 


Data set(s) from which this data set was derived. 
Value type is text string 32. Only one occurrence of 
the HISTORY keyword is allowed. Multiple values 
are allowed and imply an ordering from oldest to 
most recent. Total string count is limited to 224 
characters. 


PACKAGES 


Software package from which this data set was 
derived. Value type is text string 32. Only one occur- 
rence of the PACKAGE keyword is allowed. Mullti- 
ple values are allowed and imply an ordering from 
most to least important or from most recent to oldest 
applied. Total string count is limited to 224 charac- 
ters. 


INSTRUMENTS 


Instrument from which this data set was obtained. 
Value type is text string 32. Only one occurrence of 
the INSTRUMENT keyword is allowed. Multiple 
values are allowed and imply an ordering from most 
to least important. Total string count is limited to 
224 characters. 


Arbitrary text; value type is text string 255. Text should 
be human readable. Only one occurrence of the NOTE 
keyword is allowed and only one value is allowed. 
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The LEGAL Block 


This block is for any legal notices and the like; it begins with 


LEGAL (...) 


Only one occurrence of the LEGAL block is allowed; allowed keywords are: 


COPYRIGHT 


TRADEMARK 


OWNERSHIP 


CLASSIFY 


NOTE 


The REMARK Block 


Copyright notice. Type text string 255. Text should be 
human readable. Only one occurrence of the 
COPYRIGHT keyword is allowed and only one value is 
allowed. 


Trademark notice. Type text string 255. Text should be 
human readable. Only one occurrence of the 


TRADEMARK keyword is allowed and only one value is 


allowed. 


Ownership notice. Type text string 255. Text should be 
human readable. Only one occurrence of the OWNER- 
SHIP keyword is allowed and only one value is allowed. 


Data classification notice. Type text string 255. Text 
should be human readable. Only one occurrence of the 
CLASSIFY keyword is allowed and only one value is al- 
lowed. 


Some suggested values are (these are quoted text string 
values): 


"Company Confidential" 
“Secret” 
"Unclassified" 


Arbitrary text; value type is text string 255. Text should 
be human readable. Only one occurrence of the NOTE 
keyword is allowed and only one value is allowed. 


This block is for information not fitting elsewhere. The block may occur only 


once and begins with 


REMARK (... ) 


It takes the following keywords: 


NOTE 
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Arbitrary text; value type is text string 255. Text should 
be human readable. Only one occurrence of the NOTE 
keyword is allowed. Multiple values are allowed and no 


ordering is implied. Total string count is limited to 32767 


characters. 
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INFORMATION — Arbitrary data; value type is Definite Length Arbitrary 
Block Data (IEEE 488.2 8.7.9). Text need not be human 
readable. Only one occurrence of the NOTE keyword is 
allowed. Multiple values are allowed and no ordering is 
implied. Total byte count is limited to 32767 characters. 
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DIMENSION Blocks 


Each DIMENSION block describes one dimension of DATA(CURVE) data. 

A dimension may be either explicit, in which case values are present in the 
DATA(CURVE) block, or implicit, in which case the values are not present, but 

are instead generated by a function. The DIMENSION block requires a block ® 
modifier and begins with: 


DIMENSION = <dimension label>( ... ) 


Each dimension is uniquely distinguished by its <dimension label> modifier. 
The value type is Label and no two DIMENSION blocks can have the same 
< dimension label> value. 


It is recommended that dimension labels be kept short and meaningful, such as 
X and Y, or V and T. Note, however, these two pairs of names call for different 
ordering of the data values if Y refers to the same dimension as V and both 
dimensions are explicit. 


The DIMENSION and ORDER blocks describe the logical structure and or- 
ganization of data in the DATA(CURVE) block. The ENCODE block 
describes the physical representation or encoding of the data. The ORDER 
block describes the ordering of the dimensional data elements in the 
DATA(CURVE) block. Together they provide the sufficient and necessary in- 
formation for extraction of the data. 


Simple waveforms acquired from instruments like oscilloscopes commonly have 
one implicit dimension and one explicit dimension (when clocked internally). 
Such a waveform consists of a time series of voltage (vertical or y axis) readings. 
For each time-voltage pair, only the voltage value is present in the data; the time 
(horizontal or x axis) is given by a linear function parameterized by start time, 
time interval, and number readings. The voltage dimension is explicit and the 
time dimension is implicit. 


Whether the dimension is to be considered an independent or dependent dimen- 
sion is determined by the TRACE block. In the absence of a TRACE block, the 
following simple rule is applied: If one or more implicit dimensions are present, 
they are considered to be independent and all explicit dimensions are con- 
sidered to be dependent. 


The DIMENSION block sub-blocks and keywords are: & 


NAME Arbitrary name or description of the dimension. Value 
type is text string 32. Only one occurrence of NAME is 
allowed and only one value is allowed. 
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UNITS Units, such as volts, amps, Hz, etc., Acceptable unit valuc 
strings are those specified by IEEE 488.2 Suffix Program 
Data (7.7.3), the null string, and UNK. The null string 
implies the data has no dimensional units and UNK indi- 
cates the units are unknown. Only one occurrence of 
UNITS is allowed and only one value is allowed. If 
omitted, the default value for UNITS is UNK. 


SCALE Scaling factor to be applied to this dimension’s values in 
DATA(CURVE(VALUES)). Value type is Numeric; 
default value is 1.0. Only one occurrence of SCALE is al- 
lowed and only one value is allowed. (The SCALE value 
may be overridden ina DATA(DELTA(DIMEN- 
SION))) block.) For use, see OFFSET below. 


— 


OFFSET Offset factor to be applied to this dimension’s values in 
DATA(CURVE(VALUES)). Value type is Numeric; 
default value is 0.0. Only one occurrence of OFFSET is 
allowed and only one value is allowed. (The OFFSET 
value may be overridden in a DATA(DELTA(DIMEN- 
SION))) block.) 


OFFSET and SCALE are always applied to data from 
DATA(CURVE), but not to any other data, such as 
DATA(PULSE). OFFSET and SCALE are applied 
after any transformation specified by IMPLICIT (FUNC- 
TION). SCALE and OFFSET are applied to a depend- 
ent variable such as X to yield the independent variable 
¥: 


Y = (SCALE * X) + OFFSET 


SIZE Number of values present for an explicit dimension, or 
the index range for an implicent dimension. It is the en 
value for the running index below (see TYPE below). 
Value type is positive NR1. Only one occurrence of 
SIZE is allowed and only one value is allowed. The SIZE 
value may be overridden by DATA(DELTA(DIMEN- 
SION(SIZE)))). 

SIZE is required for all but one implicit dimension. If 
SIZE is not specified for an implicit it is determined by 
the number of data values present. 


If only one dimension is implicit, and ORDER(TYPE) is 
TUP, SIZE represents the number of n-tuples present in 
DATA(CURVE). If two or more implicit dimensions 
are present, the number of n-tuples in DATA(CURVE) 
¢& is given by the product of the SIZEs of all implicit dimen- 
sions. 

If only one dimension is implicit, and ORDER(TYPE) is 

DIM, SIZE represents the number of values present in 

DATA(CURVE) for each explicit dimension. If two or 
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more implicit dimensions are present, the number values 
in DATA(CURVE) for each explicit dimension is given 
by the product of the SIZEs of all implicit dimensions. 


If specified for explicit dimensions, and ORDER(TYPE) 
is TUP, SIZE is the number of n-tuples present in 
DATA(CURVE). It is an error if the SIZE for the ex- © 
plicit dimension does not equal the product of the SIZEs 

of all implicit dimensions. 


If specified for explicit dimensions, and ORDER(TYPE) 
is DIM, SIZE is the total number of values present in 
DATA(CURVE) for the explicit dimension. It is an 
error if the SIZE for the explicit dimension does not 
equal the product of the SIZEs of all implicit dimensions. 


If no implicit dimensions are present, SIZE must be 
specified for at least one of the explicit dimensions, if 
specified for more than one explicit dimension, they must 
all have the same value. 

TYPE Indicates if the dimension is implicit or explicit. TYPE is 
required, may occur only once, and takes one of the two 
following values: 

IMPLICIT 


Indicates the values for this dimension are not in 
DATA(CURVEB), but are generated by a function. ¢ 
The default function is LINEAR. Other functions are 
specified by a FUNCTION sub-block. 


EXPLICIT 
Indicates that the values for this dimension are 
present in DATA(CURVE). 


FUNCTION (...) |The FUNCTION sub-block specifies the generating func- 
tion for implicit dimensions. This sub-block may occur 
only once; it is ignored if the dimension type is EX- 
PLICIT. Only one of the following keywords, which 
specify the generating function for the dimension, is al- 
lowed: 


LINEAR 
The linear function: 
f(n) =n 
This keyword may occur only once. It requires a 


dummy type Numeric value of 0 that is otherwise ig- 
nored. 


SINE 
The sine function: 
f(n) = Pl sin (P2 + P3 n) 
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This keyword may occur only once. It requires threc 
type Numeric values for P1, P2, and P3, in that order. 


COSINE 
The cosine function: 
f(n) = Pl cos (P2 + P3n) 


This keyword may occur only once. It requires three 
type Numeric values for P1, P2, and P3, in that order. 


TANGENT 
The tangent function: 
f(n) = Pl tan (P2 + P3 n) 


This keyword may occur only once. It requires three 
type Numeric values for P1, P2, and P3, in that order. 


EXP 
The exponentiation function: 
f{(n) = P1 exp (P2 n) 


This keyword may occur only once. It requires two 
type Numeric values for P1, and P2, in that order. 


LN 
Natural log function: 
f(n) = Pl In (P2 + P3 n) 


This keyword may occur only once. It requires three 
type Numeric values for P1, P2, and P3, in that order. 


LOG 
Log base 10 function: 
f(n) = P1 log10 (P2 + P3 n) 


This keyword may occur only once. It requires three 
type Numeric values for P1, P2, and P3, in that order. 


NOTE Arbitrary text; value type is text string 255. Text should 
be human readable. Only one occurrence of the NOTE 
keyword is allowed and only one value is allowed. 
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The ORDER Block 


The ORDER block defines the layout of data within the DATA(CURVE) 
block. Data may be ordered as n-tuples, in which the data for each dimension is 
"inter-mixed", or the data may be ordered by dimension. When ordered by 
dimension, all data for each dimension is grouped together. Note the EN- 
CODE block defines, among other things, the manner in which each datum is 
physically encoded, but does not address the sequencing of the data. 


The ORDER block may occur only once, but is not required. If omitted, the 
default values for its keywords obtain. It must precede all DATA blocks and 
takes the following two keywords: 


SEQUENCE 


TYPE 


E-28 


Defines the dimensional sequencing of data values in 
DATA(CURVE). SEQUENCE may occur only once. 
Value is of type Label; only values defined by the 

< dimension label> modifier of a DIMENSION block 
are allowed. If present, all <dimension label> values 
must specified, without duplication, as values to SE- 
QUENCE. 


If SEQUENCE is not specified, the ordering of dimen- 
sions is determined by the ASCII collating sequence, 
from low to high, of the DIMENSION block < dimension 
label> values. That is, alphabetical order, in which digits 
occur before alphabetic characters and underscore (_) is 
the last character. 


For example, if the ADIF data set has three explicit 
dimensions and their respective < dimension label > 
values are Y2, Y4, and X, then each DATA(CURVE) 
block 3-tuple is ordered X2, Y2, Y4. Note if X2 is an im- 
plicit dimension, then only Y2 and Y4 are present and 
the order would be Y2, Y4. 
Indicates if the ordering is by tuple or dimension. TYPE 
may occur only once, and takes one of the two following 
values: 
TUP 

Data values are organized by n-tuple. Default. 
DIM 

Data values are organized by dimension. 
If ordering is by n-tuple, TUP, data values in 
DATA(CURVE(VALUES))) are sequenced as a series 
of n-tuples. 


Each n-tuple contains one value or element for each of 
the explicit dimensions. The order of the dimensions 
within the n-tuple is determined by SEQUENCE. 
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For example, assume there are two explicit dimensions, 
labeled ZU and ZL, which define an upper and a lower 
envelope, respectively. If no SEQUENCE keyword is 
present, then the 2-tuple values in 
DATA(CURVE(VALUES)) are ordered (ZL, ZU). 


G Implicit dimensions impose an ordering on the n-tuples. 
The ordering is "column wise", with the n-tuples of the 
first implicit dimension changing least frequently, and the 
last implicit dimension changing most frequently. Order- 
ing of implicit dimensions determined by SEQUENCE . 


In the above example, assume each envelope is a surface, 
defined by two implicit dimensions, labeled X and Y. If 
the number of X points is x and the number of Y points 
is y, then the (ZL, ZU) 2-tuples in 
DATA(CURVE(VALUES)) are ordered: 


(ZL, ZU)1,1, (ZL, ZU)1,2,... (ZL, ZU) Ly, ... 
(ZL, ZU)2,1, (ZL, ZU)2,2, ... (ZL, ZU)2y, ... 
(ZL, ZU)x,1, (ZL, ZU)x,2, ... (ZL, ZU)xy, 


In summary, the DATA block values are first grouped by 
explicit dimensions to form an n-tuple, and then the n- 
tuples are ordered by implicit dimension. (This is similar 
to the FORTRAN convention.) 


If ordering is by dimension, DIM, data values in 
DATA(CURVE(VALUES))) are sequenced by dimen- 
sion. All values for each dimension are grouped 
together, with the (explicit) dimensions being ordered ac- 
cording to SEQUENCE. 


The ordering of the data values within each explicit 
dimension is determined by SEQUENCE for the implicit 
dimensions. The ordering is "column wise", with the 
values for the first implicit dimension changing least fre- 
quently, and the last implicit dimension changing most 
frequently. 


For the above example, data values would be ordered as 
follows: 


(ZL11, ZL1L2, .. ZLiy), (ZL24, ZL22, « ZL3y), 
(ZLx,1, ZLx,2, ... ZLx,y) 
(ZU, ZUL 2, ZULy), (ZU2A, 23,2, «. ZU2y), 
(4011, LUI, 2, ne ZL gy) 
In summary, the DATA block values for each explicit 
dimension are first grouped by implicit dimension. Then 
é the data for each of the explicit dimensions is laid out in 
sequence according to SEQUENCE. 
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The ENCODE Block 


The ENCODE block addresses data precision, resolution, special range values, 
and encoding format for Hexadecimal Bit Numbers and Definite Length Ar- 
bitrary Block Data. 


The ENCODE block begins with 


ENCODE (... ) 


The scope of an ENCODE block is determined by its hierarchical level in the 
ADIF structure. If the ENCODE block is at the same level as DIMENSION 
blocks, it applies globally to all data in the DATA block. A global encoding 
specification can, however, be overridden on a dimension by dimension basis 
with an ENCODE block subordinate to the particular dimension. A keyword 
specification at the higher level rules unless explicitly superceded by the same 
keyword at the subordinate level. | 


Only one ENCODE block can be specified at the same hierarchical level as 
DIMENSION blocks, and only one ENCODE block can be specified subor- 
dinate to a DIMENSION block. 


If no ENCODE block is specified, the default values for each keyword obtain. 
The ENCODE block sub-blocks and keywords are: 


FORMAT Data encoding format for Hexadecimal Bit Numbers, in- 
troduced by an a pound sign X (#X), or for Definite 
Length Arbitrary Block Response Data, introduced by a 
pound sign followed by one or more decimal digit charac- 
ters (IEEE 488.2 8.7.9). See the Values section under 
Syntax. 


FORMAT applies only to the DATA block and selected 
keywords within the ENCODE block. All numeric 
values in the other blocks must be represented by type 
Numeric values. If the ENCODE block is subordinate to 
a DIMENSION block, then FORMAT applies only to 
the value in DATA(CURVE(VALUES)) for the par- 
ticular dimension. 


Only one occurrence of FORMAT is allowed and only 
one of the following values are allowed: 


INTS8 IEEE signed eight bit integer. Default. 
INT16 IEEE signed 16 bit integer 

INT32 IEEE signed 32 bit integer 

INT64 IEEE signed 64 bit integer 

SINT16 Swapped IEEE 16 bit signed integer 
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SINT32 Swapped IEEE 32 bit signed integer 
SINT64 Swapped IEEE 64 bit signed integer 
IF P32 IEEE floating point, 32 bits 
IF P64 IEEE floating point, 64 bits 

Se SFP32 IEEE swapped floating point, 32 bits 
SFP64 IEEE swapped floating point, 64 bits 
SHB32 DEC’s hidden bit floating point, 32 bits 
SHB64 DEC’s hidden bit floating point, 64 bits 
HFP32 IBM’s hexadecimal normalized, 32 bits 
HFP64 IBM’s hexadecimal normalized, 64 bits 


All integers are two’s complement. IEEE formats are 
defined by IEEE 488.2 Binary Integer Code (9.2). 
"Swapped" means the byte order (from low to high ad- 
dress) is from least significant to most significant byte. 
Note appropriate selections for DIMENSION(OFFSET) 
generally accommodate "unsigned" integer data. 


The DEC formats are represented by Digital Equipment 

Corporation’s VAX line of computers. The IBM formats 
are represented by International Business Machine’s Sys- 
tem 360/370 computer architecture. 


NOVALUE Numeric value to be treated as implying "not a number" 
or "no value recorded". Value type is Extended Numeric. 
Only one occurrence of NOVALUE is allowed and only 
one value is allowed. If not present, no no-value value is 
defined. 


OVERRANGE Numeric value to be treated as over range. Value type is 
Extended Numeric. Only one occurrence of OVER- 
RANGE is allowed and only one value is allowed. If not 
present, no overflow value is defined. 


UNDERRANGE — Numeric value to be treated as under range. Value typc 
is Extended Numeric. Only one occurrence of UNDER- 
FLOW is allowed and only one value is allowed. If not 
present, no underflow value is defined. 


HIRANGE Greatest value (before application of SCALE and OF- 

FSET for CURVE block values) allowed in the DATA 
block. Value type is Extended Numeric. Only one occur- 
rence of HIRANGE is allowed and only one value is al- 
lowed. 

@ LOWRANGE Least value (before application of SCALE and OFFSET 
for CURVE block values) allowed in the DATA block. 

Value type is Extended Numeric. Only one occurrence 

of LOWRANGE is allowed and only one value is al- 

lowed. 
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RESOLUTION Minimum resolution of data values present in the DATA 
block. Value type is Extended Numeric. Only one occur- 
rence of RESOLUTION is allowed and only one value is 
allowed. 


PRECISION (...) The precision of the representation of the data in the 
DATA block. Only one occurrence of PRECISION is al- 
lowed. This sub-block takes two keywords: 

LENGTH 
The number of significant digits regardless of how 
many digits are present in the actual representation 
of the data (ASCII or binary). Only one occurrence 
of LENGTH is allowed and only one value is al- 
lowed. If the keyword is omitted, the number of sig- 
nificant digits is unknown. A value of "0" implies only 
the digits present in each number are significant. 
RADIX 
The radix in which LENGTH is specified. Only one 
occurrence of RADIX is allowed and only one value 
is allowed. Allowed values are 2 or 10. Default is 10. 


RESOLUTION and PRECISION are related but distinct concepts. 

PRECISION specifies the accuracy of any datum by the number of significant 

digits by which it is represented. RESOLUTION specifies the accuracy of the © 
process (instrument, program, etc.) generating the data. Note the resolution 

and precision may be further limited by the actual representation of the data as 

specified by the FORMAT keyword. 


HIRANGE and LOWRANGE, may, but do not have to be the actual bounds of 
the data present. Using HIRANGE and LOWRANGE, RESOLUTION, 
PRECISION, or a combination thereof, a data processing program can make an 


intelligent decision about the size and resolution of the kind of memory element 
(16 bit integers, 32 bit floating point, etc.) to use for data storage. 


NOTE Arbitrary text; value type is text string 255. Text should 
be human readable. Only one occurrence of the NOTE 
keyword is allowed and only one value is allowed. 


TRACE Blocks 


TRACE blocks describe logical relationships among all or some of the dimen- 
sions. They may define a functions, curves, surfaces, or arbitrary sets or data i 
groupings. They also provide a convenient means of describing subsets of the 

data. The windowing effect of the TRACE blocks may, for example, be used to 

make two dimensional "cuts" through three dimensional data. 


A TRACE block requires a modifier and begins with 
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TRACE = <trace label> (... ) 


Multiple TRACE blocks are allowed; they are distinguished by a unique but op- 
tional <trace label> value. The value type is Label and no two TRACE blocks 
can have the same <trace label> value. Other blocks, such as the VIEW block, 
build on TRACE blocks. 


TRACE block information is built from DIMENSION blocks and view blocks 
are built from TRACE block information. Therefore, TRACE blocks must fol- 
low all DIMENSION blocks and precede any VIEW blocks. 


If no TRACE block is present, the independence or dependence of a dimension 
is determined by rules described in the DIMENSION Block section. 


A TRACE block takes the following sub-blocks and keywords: 


NAME Arbitrary name or description of the trace. Value type is 
text string 32. Only one occurrence of NAME is allowed 
and only one value is allowed. 


INDEPENDENT (... Identifies the independent dimension(s) constituting the 
trace. If independence and dependence are not meaning- 
ful, the trace should be defined using the INDE- 
PENDENT block. Only one occurrence of the 
INDEPENDENT sub-block is allowed; the following sub- 
block is allowed: 


DIMENSION (... ) 


Specifies one independent dimension. This sub-block 
may occur multiple times and takes the following 
keywords: 


LABEL 


The label of the independent dimension. Value is of 
type Label; only values defined by the < dimension 
label> modifier of a DIMENSION block are al- 
lowed. LABEL is required and may occur only once; 
only one value is allowed. 


START 


Specifies the starting index (inclusive). Value is of 
type positive NR1. Only one occurrence of START 
is allowed and only one value is allowed. This 
keyword may be present only if the dimension is im- 
plicit. 

If START is omitted, the default value is 1. If the 
index value is greater than the dimension’s SIZE 
value (from the applicable DIMENSION or 
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DATA(DELTA(DIMENSION))) block), then the 
value for SIZE is used. 


STOP 


Specifies the ending index (inclusive). Value is of 

type positive NR1. Only one occurrence of STOP is 

allowed and only one value is allowed. This keyword © 
may be present only if the dimension is implicit. 


If STOP is omitted, or if the index value is greater 
than the dimension’s SIZE value (from the applicable 
DIMENSION or DATA(DELTA(DIMENSION))) 
block), then the value for SIZE is used. 


If the stopping index value is greater than the starting 
index value, the stopping index value is taken to be 
the same as the starting index value. 


DEPENDENT (... ) Identifies the dependent dimension(s) constituting the 
trace. Only one occurrence of the DEPENDENT sub- 
block is allowed; the following sub-block is allowed: 


DIMENSION (... ) 


Specifies one dependent dimension. This sub-block 
may occur multiple times and takes the following 


keyword: 


LABEL | 

The label of the dependent dimension. Value is of © 
type Label; only values defined by the < dimension 

label> modifier of a DIMENSION block are al- 

lowed. LABEL is required and may occur only once; 

only one value is allowed. 


Explicit and implicit, as applied to dimensions, are 
distinguished from independent and dependent as fol- 
lows. Implicit and explicit are concerned with how 
the data is physically represented and structured. In- 
dependent and dependent relate to how a dimension 
is interpreted. 


SYMMETRY Specifies the type of symmetry on a per dimension basis. 
Only one occurrence of SYMMETRY is allowed and 
only one of the following values is allowed: 


UNK Symmetry is unknown (default). 

NONE No symmetry. 

PEVEN Positive and even symmetry. 

NEVEN Negative and even symmetry. @ 
PODD Positive and odd symmetry. 

NODD Negative and odd symmetry. 
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NOTE Arbitrary text; value type is text string 255. Text should 
be human readable. Only one occurrence of the NOTE 
keyword is allowed and only one value is allowed. 


VIEW Blocks 


VIEW blocks provide semantic information about the data in DATA(CURVE). 
With a VIEW block, one can show relationships between and among subsets of 
the data as defined by TRACE blocks. For example, a complex waveform or 
surface can be easily defined, as can a waveform and its upper and lower en- 
velopes. 


The VIEW block builds on traces described in a TRACE block. A trace com- 
monly defines a simple function, but ADIF allows for the definition of sets, sur- 
faces and other complex functions. 


For example, a time varying envelope might be described by three DIMEN- 
SION blocks as a 2-tuple. The two explicit dimensions define the y-axis for the 
upper and lower components of the envelope. The implicit dimension defines 
the common x-axis. While the organizational structure of the data is defined by 
the DIMENSION blocks, its meaning is determined by a VIEW block. The 
view block identifies which dimension is the upper envelope and which is the 
lower. 


Alternatively, the same data could be viewed as a complex waveform. The 
DIMENSION blocks would be the same, but a VIEW block would identify 
which dimension is the real component and which is the complex component. 


Multiple VIEW block occurrences are allowed. The <view label> is optional 
and allows for the unique identification of the VIEW block; no two VIEW 
blocks may have the same <view label>. The VIEW block begins with 


VIEW = <view label> (... ) 


and takes the following sub-blocks and keywords: 


NAME Name of the view; typically more descriptive than <view 
label> and does not need to be unique. Value type is 
text string 32. Only one occurrence of NAME is allowed 
and only one value is allowed. 


ENVELOPE (...) Identifies which two traces constitute the envelope for a 
third in DATA(CURVE) data. Multiple occurrences of 
ENVELOPE are allowed and it takes the following 
keywords: 
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UPPER 


Specifies the name of the upper envelope trace. 

Value type is Label and is restricted to a value 

defined by the <trace label> modifier of a TRACE 

block. Only one occurrence of UPPER is allowed 

and only one value is allowed. ©} 


LOWER 
Specifies the name of the lower envelope trace. 
Value type is Label and is restricted to a value 
defined by the <trace label> modifier of a TRACE 


block. Only one occurrence of LOWER is allowed 
and only one value is allowed. 


FUNCTION 


Specifies the name of the function being enveloped. 
Value type is Label and is restricted to a value 
defined by the <trace label> modifier of a TRACE 
block. Only one occurrence of FUNCTION is al- 
lowed and only one value is allowed. 


COMPLEX (... ) 


Identifies which two traces constitute the real and 
complex components of a complex set of 


DATA(CURVE) data. Multiple occurrences of 
COMPLEX are allowed and it takes the following 
keywords: 

REAL 


Specifies the name of the real component. Value 
type is Label and is restricted to a value defined by 
the <trace label> modifier of a TRACE block. Only 
one occurrence of REAL is allowed and only one 
value is allowed. 


IMAGINARY 


Specifies the name of the imaginary component. 
Value type is Label and is restricted to a value 
defined by the <trace label> modifier of a TRACE 
block. Only one occurrence of REAL is allowed and 
only one value is allowed. 


POLAR (.... ) 


Identifies which two traces constitute the magnitude 
and phase components of a polar set of 
DATA(CURVE) data. Multiple occurrences of 
POLAR are allowed and it takes the following 
keywords: 
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MAGNITUDE 


Specifies the name of the magnitude component. 
Value type is Label and is restricted to a value 
defined by the <trace label> modifier of a TRACE 
block. Only one occurrence of MAGNITUDE is al- 
lowed and only one valuc is allowed. 


PHASE 


Specifies the name of the imaginary component. 
Value type is Label and is restricted to a value 
defined by the <trace label> modifier of a TRACE 
block. Only one occurrence of PHASE is allowed 
and only one value is allowed. 


BODE (... ) Identifies which two traces constitute the magnitude and 
phase components of a bode set of DATA(CURVE) 
data. Multiple occurrences of BODE are allowed and it 
takes the following keywords: 


MAGNITUDE 


Specifies the name of the magnitude component. 
Value type is Label and is restricted to a value 
defined by the <trace label> modifier of aTRACE 
block. Only one occurrence of MAGNITUDE is al- 
lowed and only one value is allowed. 


PHASE 
Specifies the name of the imaginary component. 
Value type is Label and is restricted to a value 
defined by the <trace label> modifier of a TRACE 
block. Only one occurrence of PHASE is allowed 
and only one value is allowed. 


SET (... ) Identifies data certain identified attributes. Multiple oc- 
currences of SET are allowed; the keywords are: 


NAME 


Arbitrary set name or description. Value type is text 
string 32. Only one occurrence of NAME is allowed 
and only one value is allowed. 


ATTRIBUTE 


Identifies attribute type of the set. ATTRIBUTE is 
optional and can occur only once. The following 
values are predefined: 


IPL 
Interpolated point(s). 
UNK 


Unknown or false data point(s). 
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EXC 

Excursion or exceptional point(s). 
EMP 

Emphasized point(s). \ 


NOTE ® 


Since the VIEW block applies to all DATA blocks, attributes also 
apply to all DATA blocks in the particular ADIF data set. See the 
POINT sub-block in the DATA block: 


ELEMENTS 


Specifies the name of the user selected components. 
Value type is Label and is restricted to a values 
defined by the <trace label> modifier of a TRACE 
block. Only one occurrence of ELEMENTS is al- 
lowed, but more than one value is allowed. 


NOTE Arbitrary text; value type is text string 255. Text should 
be human readable. Only one occurrence of the NOTE 
keyword is allowed and only one value is allowed. 


DATA Blocks 


DATA blocks, naturally, contain data. It may contain dimensioned data such as 6 
DATA(CURVE), or specific sets of data (PULSE, SINE, ST: ATISTICS, etc.). 
Multiple DATA block are allowed; they begin with 


DATA = <data label> (... ) 


The <data label> is optional and allows for the unique identification of the 
DATA block; no two DATA blocks may have the same < data label> value. 
The value type of < data label> is Label. 


The subordinate blocks within a particular DATA block are assumed to be re- 
lated. That is, if CURVE and PULSE measurements are present in the same 
DATA block, the PULSE measurements are assumed to have been derived 
from the CURVE data. If this is not the case, different DATA blocks should be 
used for the CURVE and PULSE measurements. 


The DATA block sub-blocks and keywords are: 


DELTA = <delta label> (... ) © 
DELTA sub-blocks provide a mechanism for sequences 


of closely related data. When the data set contains multi- 
ple occurrences of DATA blocks, the DELTA block 
provides a simple mechanism for specifying those charac- 
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teristics differentiating each of the DATA blocks. Note 
the DELTA blocks are limited to redefining descriptive 
and encoding information, such as SCALE, DATE, and 
FORMAT; a DELTA block cannot change the organiza- 
tion of the data, such as the number of dimensions or the 


© data ordering. 

The values specified in a DELTA block override those 
specified at a higher hierarchical level. For example, the 
value for SCALE in the DATA(DELTA(DIMEN- 
SION)) block overrides the value for SCALE in the 
higher level DIMENSION block, but only for data within 
the DATA block containing the DELTA block. If there 
are multiple DATA blocks with subordinate DELTA 
blocks, the DELTA blocks have no effect on each other; 
that is, the each, individually, specify a modification of 
the same, higher level, IDENTIFY, DIMENSION, or 
ENCODE block. 


The DELTA block may occur only once and, if present, 
must be the first block in the DATA block. 


The <delta label> is optional and allows for the unique 
identification of the DELTA block; no two DELTA 
blocks may have the same < delta label> value. The 
value type of <delta label> is Label. 


The DELTA block sub-blocks are: 
DIMENSION 


The DIMENSION sub-block is a limited subset of 
the higher level DIMENSION block. It may occur 
only once and only the following keywords are al- 
lowed: 


LABEL 


The label of the dimension for which certain keyword 
values are to be redefined within the particular 
DATA block. Value is of type Label; only values 
defined by the <dimension label> modifier of a 
DIMENSION block are allowed. LABEL is required 
and may occur only once; only one value is allowed. 


SCALE 


The scale value for the dimension specified by 
LABEL. SCALE may occur only once; it is other- 
wise defined the same as for DIMENSION(SCALE). 


©} OFFSET 


The offset value for the dimension specified by 
LABEL. OFFSET may occur only once; it is other- 
wise defined the same as for DIMENSION(OF- 
FSET). 
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SIZE 


The size value for the dimension specified by 
LABEL. SIZE may occur only once; it is otherwise 
defined the same as for DIMENSION(SIZE). 


IDENTIFY 


This sub-block is the same as the IDENTIFY block. 
It may occur only once. It takes the same sub-blocks 
and keywords as the IDENTIFY block but their 
values apply only within the DATA block containing 
this DELTA(IDENTIFY) sub-block. 


ENCODE 


This sub-block is the same as the ENCODE block. It 
may occur only once. It takes the same sub-blocks 
and keywords as the ENCODE block but their values 
apply only within the DATA block containing this 
DELTA(ENCODE) sub-block. 


CURVE = <curve label> (... ) 


Only one CURVE definition is permitted ina DATA 
block. CURVE data is dimensioned; its structure and 
physical representation is defined by DIMENSION, 
ORDER, and ENCODE blocks. 


DATA(CURVE(VALUES)) may be organized as n- 
tuples are by dimension; this is determined by the 
ORDER block or, in its absence, the defaults for the 
TYPE and SEQUENCE keywords in the ORDER block. 


The physical format of each value is determined by the 
applicable ENCODE block. If the dimension has a sub- 
ordinate ENCODE block, it rules; otherwise the EN- 
CODE block at the same hierarchical level as the 
DIMENSION blocks rules. 

Multiple occurrences of CURVE are allowed. The 
<curve label> is optional and allows for the unique iden- 
tification of the DATA(CURVE) block; no two 
DATA(CURVE) blocks may have the same <curve 
label>. The value type of <curve label> is Label. 
CURVE takes the following keywords: 


VALUES 


The data values. Value type is Extended Numeric or 
Definite Length Arbitrary Block Response Data 
(IEEE 488.2 8.7.9). VALUES is required and may 
occur only once. Multiple values are allowed. 

More than one Definite Length Arbitrary Block 
Response Data value is permitted. This simplifies 
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the output task when the total number of values is 
not known prior to the beginning of output. 


Note the ENCODE block specifies the interpretation 
of data if it is Definite Length Arbitrary Block 
Response Data or Hexadecimal Bit data. 


NAME 


Arbitrary name or description of the curve; typically 
more descriptive than <curve label> and it does not 
have to be unique. Value type is string 32. NAME 
may occur only once and only one value is allowed. 


SUMCHECK 


Checksum for DATA(CURVE(VALUES) data. 
Value type is NR1. The checksum is computed ac- 
cording to the rules specified by CHECKTYPE. If 
data is in ASCII, the checksum is computed using the 
eight bit ASCII decimal equivalent of each character 
of the number. This includes all signs, decimal 
points, and exponent characters. In the case of 
Hexadecimal Bit Numbers, embedded white space is 
excluded. 


SUMCHECK may occur only once and takes only 
one value. 


~CHECKTYPE 


Checksum type. CHECKTYPE may occur only once 
and requires one and only one of the following values: 


CRC8 eight bit cyclic redundancy check (default). 
CRC16 16 bit cyclic redundancy check. 
CCITT CCITT 16 bit cyclic redundancy check. 


PULSE = <pulse label> (... ) 


Pulse parameter measurements of a two dimensional 
curve. Multiple occurrences of PULSE are allowed. The 
<pulse label> is optional and allows for the unique iden- 
tification of the PULSE sub-block; no two PULSE sub- 
blocks may have the same <pulse label>. The value 
type of <pulse label> is Label. 


If PULSE measurements are found together with a 
CURVE block in a DATA block, they are considered to 
be derived from the CURVE data (or a subset of it). 
Since pulse measurements are inherently measurements 
of two dimensional data, either the data in CURVE must 
be two dimensional or the TRACE keyword must be 
present and must refer to a two dimensional subset of the 
data in the CURVE block. 
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It is permissible for an ADIF data set to contain pulse 
measurements without a DATA(CURVE) block, but a 
DIMENSION block for the independent dimension must 
still be specified. 


PULSE takes the following keywords: 
NAME 


Arbitrary name of the pulse measurement, typically 
more descriptive than <pulse label> and it does not 
have to be unique. Value type is string 32. NAME 
may occur only once and only one value is allowed. 


TRACE 


Trace from which the pulse parameters were ex- 
tracted. Value type is label; only values defined by 
the <dimension label> modifier of a DIMENSION 
block are allowed. Only one occurrence of TRACE 
is allowed and only one value is allowed. The 
TRACE referenced must be two dimensional. 


START 


Specifies the starting index (inclusive) of the inde- 
pendent dimension. START is constrained to a value 
in the TRACE range if the TRACE keyword is 
present. Value is of type positive NR1. Only one oc- 
currence of START is allowed and only one value is 
allowed. 


If START is omitted, the default value is 1. If the 
index value is greater than the dimension’s SIZE 
value (from the applicable DIMENSION or 
DATA(DELTA(DIMENSION))) block), then the 
value for SIZE is used. 


STOP 


Specifies the ending index (inclusive) of the inde- 
pendent dimension. STOP is constrained to a value 
in the TRACE range if the TRACE keyword is 
present. Value is of type positive NR1. Only one oc- 
currence of STOP is allowed and only one value is al- 
lowed. 


If STOP is omitted the value for SIZE the applicable 
DIMENSION or DATA(DELTA(DIMENSION))) 
block is used. If the index value is greater than the 
dimension’s SIZE value then the value for SIZE is 
used. 


If the stopping index value is greater than the starting 
index value, the stopping index value is taken to be 
the same as the starting index value. 
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AMPLITUDE 


Pulse amplitude. Value type is positive Extended 
Numeric. Value is required if keyword is present. 


AMPLITUDE may occur only once and only one 


value is allowed. 
@ WIDTH 


Pulse width. Value type is positive Extended 
Numeric. Value is required if keyword is present. 
WIDTH may occur only once and only one value is al- 
lowed. 


DUTYFACTOR 


Pulse duty factor (the percentage of the pulse which 
has an amplitude greater than 
<PULSE(AMPLITUDE)> / 2). Value type is posi- 
tive Extended Numeric. Value is required if keyword 
is present. DUTYFACTOR may occur only once 
and only one value is allowed. 


PERIOD 


Pulse period. Value type is positive Extended 
Numeric. Value is required if keyword is present. 
PERIOD may occur only once and only one value is 
allowed. 


RISE 


Rise time. Value type is positive Extended Numeric. 
Value is required if keyword is present. RISE may 
occur only once and only one value is allowed. 


FALL 


Fall time. Value type is positive Extended Numeric. 
Value is required if keyword is present. FALL may 
occur only once and only one value is allowed. 


RPROXIMAL 


Rising proximal value. Value type is positive Ex- 
tended Numeric. Value is required if keyword is 
present. RPROXIMAL may occur only once and 
only one value is allowed. 


RDISTAL 
Rising distal value. Value type is positive Extended 
Numeric. Value is required if keyword is present. 
6 RDISTAL may occur only once and only one value is 
allowed. 
RMESIAL 


Rising mesial value. Value type is positive Extended 
Numeric. Value is required if keyword is present. 
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RMESIAL may occur only once and only one value is 
allowed. 


FPROXIMAL 


Falling proximal value. Value type is positive Ex- 
tended Numeric. Value is required if keyword is 
present. FPROXIMAL may occur only once and 
only one value is allowed. 


FDISTAL 


Falling distal value. Value type is positive Extended 
Numeric. Value is required if keyword is present. 
FDISTAL may occur only once and only one value is 
allowed. 


FMESIAL 


Falling mesial value. Value type is positive Extended 
Numeric. Value is required if keyword is present. 
FMESIAL may occur only once and only one value is 
allowed. 


PROXIMALPCT 


Proximal percent. Value type is positive Extended 
Numeric in the range 0 to 100; default value is 10%. 
PROXIMALPCT may occur only once and only one 
value is allowed. 


DISTALPCT @ 


Distal percent. Value type is positive Extended 
Numeric in the range 0 to 100; default value is 90%. 
DISTALPCT may occur only once and only one 
value is allowed. 


MESIALPCT 


Proximal percent. Value type is positive Extended 
Numeric in the range 0 to 100; default value is 50%. 
MESIALPCT may occur only once and only one 
value is allowed. 


EOAA 
End of Array algorithm employed when the data was 


generated. EOAA may occur only once and only one 
of the following values is allowed: 


UNK Not known if any algorithm was applied. 
Default. 
NONE End of array algorithm not applied. 
REP Ending values repeated ® 
BOU "Bounce" off end values. 
INV Bounce and invert end values. 
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WRAP 

Wrap around to other end values. 
ZERO 

End values taken as zero. 
SUMCHECK 


Checksum for all DATA(CURVE(PULSE) values 
for keywords taking Numeric or Extended Numeric 
value types. Value type is NR1. The checksum is 
computed according to the rules specified by 
CHECKTYPE. If data is in ASCII, the checksum is 
computed using the eight bit ASCII decimal 
equivalent of each character of the number. This in- 
cludes all signs, decimal points, and exponent charac- 
ters. In the case of Hexadecimal Bit Numbers, 
embedded white space is excluded. 


SUMCHECK may occur only once and takes only 
one value. 


CHECKTYPE 


Checksum type. CHECKTYPE may occur only once 
and requires one and only one of the values specified 
for CHECKTYPE under DATA(CURVE). 


fa} 


Sine parameter measurements of a two dimensional 
curve. Multiple occurrences of SINE are allowed. The 

< sine label> is optional and allows for the unique iden- 
tification of the SINE sub-block; no two SINE sub-blocks 
may have the same <sine label>. The value type of 
<sine label> is Label. 


If SINE measurements are found together with a 
CURVE block in a DATA block, they are considered to 
be derived from the CURVE data (or a subset of it). 
Since sine measurements are inherently measurements of 
two dimensional data, either the data in CURVE must 
be two dimensional or the TRACE keyword must be 
present and must refer to a two dimensional subset of the 
data in the CURVE block. 


It is permissible for an ADIF data set to contain sine 
measurements without a DATA(CURVE) block, but a 
DIMENSION block for the independent dimension must 
still be specified. 


SINE takes the following keywords: 
NAME 


Arbitrary name of the sine measurement; typically 
more descriptive than <sine label> and it does not 
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have to be unique. Value type is string 32. NAME 
may occur only once and only one value is allowed. 


TRACE 


Trace from which the sine parameters were extracted. 

Value type is label; only values defined by the 

< dimension label> modifier of a DIMENSION _ 
block are allowed. Only one occurrence of TRACE 

is allowed and only one value is allowed. 


START 


Specifies the starting index (inclusive) of the inde- 
pendent dimension. START is constrained to a value 
in the TRACE range if the TRACE keyword is 
present. Value is of type positive NR1. Only one oc- 
currence of START is allowed and only one value is 
allowed. 


If START is omitted, the default value is 1. If the 
index value is greater than the dimension’s SIZE 
value (from the applicable DIMENSION or 
DATA(DELTA(DIMENSION))) block), then the 
value for SIZE is used. 


STOP 


Specifies the ending index (inclusive) of the inde- 

pendent dimension. STOP is constrained to a value 

in the TRACE range if the TRACE keyword is © 
present. Value is of type positive NR1. Only one oc- 

currence of STOP is allowed and only one value is al- 

lowed. 


If STOP is omitted the value for SIZE the applicable 
DIMENSION or DATA(DELTA(DIMENSION))) 
block is used. If the index value is greater than the 
dimension’s SIZE value then the value for SIZE is 
used. 

If the stopping index value is greater than the starting 
index value, the stopping index value is taken to be 
the same as the starting index value. 


AMPLITUDE 
Sine amplitude. Value type is positive Extended 


Numeric. AMPLITUDE may occur only once and 
only one value is allowed. 


FREQUENCY 
Sine frequency. Value type is positive Extended 


Numeric. FREQUENCY may occur only once and 
only one value is allowed. 
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PHASE 


Sine phase. Value type is Extended Numeric. 
PHASE may occur only once and only one value is al- 
lowed. 


© UNITS 
Units associated with PHASE value. UNITS may 
occur only once and only one of the following values 
is allowed: 


DEG Degrees. ~(Default). 

GRA Grads. 

RAD Radians. 
SUMCHECK 


Checksum for all DATA(CURVE(PULSE) values 
for keywords taking Numeric or Extended Numeric 
value types. Value type is NR1. The checksum is 
computed according to the rules specified by 
CHECKTYPE. If data is in ASCII, the checksum is 
computed using the eight bit ASCII decimal 
equivalent of each character of the number. This in- 
cludes all signs, decimal points, and exponent charac- 
ters. In the case of Hexadecimal Bit Numbers, 


©} embedded white space is excluded. 


SUMCHECK may occur only once and takes only 
one value. 


CHECKTYPE 


Checksum type. CHECKTYPE may occur only once 
and requires one and only one of the values specified 
for CHECKTYPE under DATA(CURVE). 


STATISTICS = <statistics label> (... ) 


Statistical measurements. Multiple occurrences of 
STATISTICS are allowed. The <statistics label> is op- 
tional and allows for the unique identification of the 
STATISTICS sub-block; no two STATISTICS sub-blocks 
may have the same <statistics label>. The value type of 
< statistics label> is Label. 


If STATISTICS measurements are found together with a 
CURVE block in a DATA block, they are considered to 
be derived from the CURVE data (or a subset of it). 


@ It is permissible for an ADIF data set to contain statistics 
measurements without a DATA(CURVE) block or any 
DIMENSION blocks. In such a case, the START and 
STOP keywords may still be specified. 


STATISTICS takes the following keywords: 
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NAME 


Arbitrary name of the statistical measurements, typi- 
cally more descriptive than < statistics label> and it 
does not have to be unique. Value type is string 32. 
NAME may occur only once and only one value is al- 
lowed. 


TRACE 


Trace from which the statistical parameters were ex- 
tracted. Value type is label; only values defined by 
the <trace label> modifier of a TRACE block are al- 
lowed. Only one occurrence of TRACE is allowed 
and only one value is allowed. 


START 


Specifies the starting index (inclusive) of the inde- 
pendent dimension. START is constrained to a value 
in the TRACE range if the TRACE keyword 1s 
present. Value is of type positive NR1. Only one oc- 
currence of START is allowed and only one value is 
allowed. 


If START is omitted, the default value is 1. If the 
DAT(CURVE) block is present and if the index 
value is greater than the dimension’s SIZE value 
(from the applicable DIMENSION or 
DATA(DELTA(DIMENSION))) block), then the 
value for SIZE is used. 


STOP 


Specifies the ending index (inclusive) of the inde- 
pendent dimension. STOP is constrained to a value 
in the TRACE range if the TRACE keyword is 
present. Value is of type positive NR1. Only one oc- 
currence of STOP is allowed and only one value is al- 
lowed. 


If STOP is omitted the value for SIZE the applicable 
DIMENSION or DATA(DELTA(DIMENSION))) 
block is used. If the DATA(CURVE) block is 
present, and if the index value is greater than the 
dimension’s SIZE value then the value for SIZE is 
used. 


If the stopping index value is greater than the starting 
index value, the stopping index value is taken to be 
the same as the starting index value. 


MAXIMUM 


Maximum value. Value type is Extended Numeric. 
MAXIMUM may occur only once and only one value 
is allowed. 
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MINIMUM 


Minimum value. Value type is Extended Numeric. 
MINIMUM may occur only once and only one value 
is allowed. 


S$ MEAN 
Mean value. Value type is Extended Numeric. 


MEAN may occur only once and only one value is al- 
lowed. 


DEVIATION 


Standard deviation. Value type is Extended Numeric. 
DEVIATION may occur only once and only one 
value is allowed. 


VARIANCE 


Variance. Value type is Extended Numeric. 
VARIANCE may occur only once and only one value 
is allowed. 


SUMCHECK 


Checksum for all DATA(CURVE(PULSE) values 
for keywords taking Numeric or Extended Numeric 
value types. Value type is NR1. The checksum is 
computed according to the rules specified by 
CHECKTYPE. If data is in ASCII, the checksum is 
computed using the eight bit ASCII] decimal 
equivalent of each character of the number. This in- 
cludes all signs, decimal points, and exponent charac- 
ters. In the case of Hexadecimal Bit Numbers, 
embedded white space is excluded. 


SUMCHECK may occur only once and takes only 
one value. 


CHECKTYPE 


Checksum type. CHECKTYPE may occur only once 


and requires one and only one of the values specified 
for CHECKTYPE under DATA(CURVE). 


POINT = <point label> (... ) 


A point, or measurement associated with a point. The 
<point label> is optional and is used to identify the type 
of point. More than one POINT block may have the 
same <point label>. The value type of <point label > 
is Label. The following <point label> values are 
predefined: 

TRG Trigger point. 

MAN Manually selected point. 


CUR Cursor point. 
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IPL Interpolated point. 
UNK Unknown or false data point. 
EXC Excursion or exceptional point. 


The POINT block differs from the MEASUREMENT 


block in that a measurement must be associated with a 
specific point in DATA(CURVE). 


A POINT block may occur multiple times and takes the 


following keywords: 
NAME 


Arbitrary name of the measurement; typically more 
descriptive than <point label> and it does not have 


to be unique. Value type is string 32. NAME may 
occur only once and only one value is allowed. 


TRACE 


Trace associated with the point(s). Value type is 
Label; only values defined by the <trace label> 


modifier of a TRACE block are allowed. Only one 
occurrence of TRACE is allowed and only one value 
is allowed. If this keyword is present, it determines 
which dimensions must be included in the DIMEN- 


SION sub-block for POINT. 
LOCATION (... ) 
Specifies the label and index for one independent 


dimension. This sub-block is required and may occur 
multiple times. There must be a DIMENSION sub- 
block with a label value for each independent dimen- 


sion present, or if a TRACE keyword is specified, 


then for each independent dimension in the specified 


trace. LOCATION takes the following keywords: 
LABEL 


The label of the independent dimension. Value is of 
type Label. Only values defined by the < dimension 
label> modifier of a DIMENSION block are allowed 


and the dimension must be implicit. LABEL is re- 


quired and may occur only once; only one value is al- 


lowed. 
INDEX 
Specifies the index for the point. Value is of type 


positive NR1. INDEX is required and only one oc- 
currence of INDEX is allowed. The index value may 


be outside the index range of the data (1 to SIZE 
from the applicable DIMENSION or 


DATA(DELTA(DIMENSION))) block), thus iden- 


tifying a point not included in DATA(CURVE). 
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UNITS 


Units, such as volts, amps, Hz, etc. Acceptable unit 
value strings are those specified by IEEE 488.2 Suffix 
Program Data (7.7.3), the null string, and UNK. The 
null string implies the data has no dimensional units 
and UNK indicates the units are unknown. Units 
need not be the same as the units specified for dimen- 
sions defined in the TRACE block. Only one occur- 
rence of UNITS is allowed and only one value is 
allowed. If omitted, the default value for UNITS is 
UNK. 


VALUES 


The data value(s). Value type is Extended Numeric. 
VALUES is optional and may occur only once. Mul- 
tiple values are allowed. 


Note that the ENCODE block specifies the inter- 
pretation of data if it is Definite Length Arbitrary 
Block Response Data or Hexadecimal Bit data. 


PARAMETER = <parameter label> (...) 


Parameter values associated with the point. The 
PARAMETER sub-block may occur multiple times, 
however, the ordering of PARAMETER sub-blocks 
has no meaning. The <parameter label> is optional 
and is used to identify the type of parameter. More 
than one PARAMETER block may have the same 
<parameter label>; the following <parameter 
label> values are predefined: 


LTRG _ Trigger level. 

DTRG Trigger delay. 
PARAMETER takes the following keywords: 
VALUE 
Parameter value. Value type is Extended Numeric. 


VALUE may occur only once; multiple values are al- 
lowed. 


UNITS 


Units, such as volts, amps, Hz, etc., Acceptable unit 
value strings are those specified by IEEE 488.2 Suffix 
Program Data (7.7.3), the null string, and UNK. The 
null string implies the data has no dimensional units 
and UNK indicates the units are unknown. Units 
need not be the same as the units specified for dimen- 
sions defined in the TRACE block. Only one occur- 
rence of UNITS is allowed and only one value is 
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allowed. If omitted, the default value for UNITS is 
UNK. 


SUMCHECK 


Checksum for all DATA(POINT(VALUES)) data. 
Value type is NR1. The checksum is computed ac- 
cording to the rules specified by CHECKTYPE. If 
data is in ASCII, the checksum is computed using the 
eight bit ASCII decimal equivalent of each character 
of the number. This includes all signs, decimal 
points, and exponent characters. In the case of 
Hexadecimal Bit Numbers, embedded white space is 
excluded. 


SUMCHECK may occur only once and takes only 
one value. 
CHECKTYPE 


Checksum type. CHECKTYPE may occur only once 
and requires one and only one of the values specified 
for CHECKTYPE under DATA(CURVE). 


MEASUREMENT = <measurement label> (... ) 
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Single valued measurements. A MEASUREMENT 
block may occur multiple times. The <measurement 
label> is optional and is used to uniquely identify the 
type of measurement. More than one MEASURE- 
MENT sub-block may have the same < measurement 
label>. The value type of <measurement label> is 
Label. 


The MEASUREMENT block differs from the POINT 
block in that no association of a measurement with a 
specific point is required. The TRACE keyword allows 
association of the measurement with an arbitrary subset 
of CURVE data. 


MEASUREMENT takes the following keywords: 
NAME 


Arbitrary name of the measurement, typically more 
descriptive than <measurement label> and it does 
not have to be unique. Value type is string 32. 
NAME may occur only once and only one value is al- 
lowed. 


TRACE 


Trace associated with the measurements. Value type 
is label; only values defined by the <trace label> 
modifier of a TRACE block are allowed. Only one 
occurrence of TRACE is allowed and only one value 
is allowed. 
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If keyword TRACE is omitted, there is no association 
of MEASUREMENT with any dimensions. 


UNITS 


Units, such as volts, amps, Hz, etc., Acceptable unit 
value strings are those specified by IEEE 488.2 Suffix 
Program Data (7.7.3), the null string, and UNK. The 
null string implies the data has no dimensional units 
and UNK indicates the units are unknown. Units 
need not be the same as the units specified for dimen- 
sions defined in the TRACE block. Only one occur- 
rence of UNITS is allowed and only one value is 
allowed. If omitted, the default value for UNITS is 
UNK. 


PARAMETER = <parameter label> (...) 


Parameter values associated with the point. The 
PARAMETER sub-block may occur multiple times, 
however, the ordering of PARAMETER sub-blocks 
has no meaning. The <parameter label> is optional 
and is used to identify the type of parameter. More 
than one PARAMETER block may have the same 

< parameter label>; the following <parameter 
label> values are predefined: 


LTRG Trigger level. 

DTRG _ Trigger delay. 

PARAMETER takes the following keywords: 
VALUE 


Parameter value. Value type is Extended Numeric. 
VALUE may occur only once; multiple values are al- 
lowed. 


UNITS 


Units, such as volts, amps, Hz, etc., Acceptable unit 
value strings are those specified by IEEE 488.2 Suffix 
Program Data (7.7.3), the null string, and UNK. The 
null string implies the data has no dimensional units 
and UNK indicates the units are unknown. Only one 
occurrence of UNITS is allowed and only one value is 
allowed. If omitted, the default value for UNITS is 
UNK. 


VALUES 


The data value(s). Value type is Extended Numeric. 
VALUES is optional and may occur only once. Mul- 
tiple values are allowed. 
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Note that the ENCODE block specifies the inter- 
pretation of data if it is Definite Length Arbitrary 
Block Response Data or Hexadecimal Bit data. 


SUMCHECK 


Checksum for all DATA(MEASURE- 
MENT(VALUES)) data. Value type is NR1. The 

checksum is computed according to the rules 

specified by CHECKTYPE. If data is in ASCII, the 

checksum is computed using the eight bit ASCIT 

decimal equivalent of each character of the number. 

This includes all signs, decimal points, and exponent 
characters. In the case of Hexadecimal Bit Numbers, 
embedded white space is excluded. 


SUMCHECK may occur only once and takes only 
one value. 


CHECKTYPE 


Checksum type. CHECKTYPE may occur only once 
and requires one and only one of the values specified 
for CHECKTYPE under DATA(CURVE). 
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MANUAL CHANGE INFORMATION 


At Tektronix, we continually strive to keep up with 
latest electronic developments by adding circuit and 
component improvements to our instruments as soon as 
they are developed and tested. 


Sometimes, due _ to_ printing and_ shipping 
requirements, we can’t get these changes immediately 
into printed manuals. Hence, your manual may contain 
new change information on following pages. 


A single change may affect several sections. Since 
the change information sheets are carried in the manual 
until all changes are permanently entered, some 
duplication may occur. If no such change pages appear 
following this page, your manual is correct as printed. 
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